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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma-next/cli",
-  "version": "0.4.0-dev.6",
+  "version": "0.4.0-dev.7",
   "type": "module",
   "sideEffects": false,
   "files": [
@@ -24,28 +24,28 @@
     "string-width": "^8.2.0",
     "strip-ansi": "^7.1.2",
     "wrap-ansi": "^10.0.0",
-    "@prisma-next/config": "0.4.0-dev.6",
-    "@prisma-next/contract": "0.4.0-dev.6",
-    "@prisma-next/emitter": "0.4.0-dev.6",
-    "@prisma-next/framework-components": "0.4.0-dev.6",
-    "@prisma-next/psl-printer": "0.4.0-dev.6",
-    "@prisma-next/migration-tools": "0.4.0-dev.6",
-    "@prisma-next/errors": "0.4.0-dev.6",
-    "@prisma-next/utils": "0.4.0-dev.6"
+    "@prisma-next/config": "0.4.0-dev.7",
+    "@prisma-next/contract": "0.4.0-dev.7",
+    "@prisma-next/emitter": "0.4.0-dev.7",
+    "@prisma-next/framework-components": "0.4.0-dev.7",
+    "@prisma-next/errors": "0.4.0-dev.7",
+    "@prisma-next/psl-printer": "0.4.0-dev.7",
+    "@prisma-next/utils": "0.4.0-dev.7",
+    "@prisma-next/migration-tools": "0.4.0-dev.7"
   },
   "devDependencies": {
     "@types/node": "24.10.4",
     "tsdown": "0.18.4",
     "typescript": "5.9.3",
     "vitest": "4.0.17",
-    "@prisma-next/sql-contract": "0.4.0-dev.6",
-    "@prisma-next/sql-contract-emitter": "0.4.0-dev.6",
-    "@prisma-next/sql-contract-ts": "0.4.0-dev.6",
-    "@prisma-next/sql-operations": "0.4.0-dev.6",
-    "@prisma-next/tsdown": "0.0.0",
+    "@prisma-next/sql-contract-emitter": "0.4.0-dev.7",
+    "@prisma-next/sql-contract": "0.4.0-dev.7",
+    "@prisma-next/sql-contract-ts": "0.4.0-dev.7",
+    "@prisma-next/sql-runtime": "0.4.0-dev.7",
+    "@prisma-next/sql-operations": "0.4.0-dev.7",
     "@prisma-next/tsconfig": "0.0.0",
-    "@prisma-next/sql-runtime": "0.4.0-dev.6",
-    "@prisma-next/test-utils": "0.0.1"
+    "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/tsdown": "0.0.0"
   },
   "exports": {
     ".": {

package/src/commands/migration-emit.ts

@@ -105,7 +105,9 @@ export function createMigrationEmitCommand(): Command {
     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 manifest.json.',
+      '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)

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 emit` 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)}`,

package/src/commands/migration-plan.ts

@@ -1,9 +1,14 @@
 import { readFile } from 'node:fs/promises';
 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 } from '@prisma-next/migration-tools/dag';
-import { formatMigrationDirName, writeMigrationPackage } from '@prisma-next/migration-tools/io';
-import { scaffoldMigrationTs } from '@prisma-next/migration-tools/migration-ts';
+import {
+  copyContractToMigrationDir,
+  formatMigrationDirName,
+  writeMigrationPackage,
+} from '@prisma-next/migration-tools/io';
+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';
@@ -11,6 +16,7 @@ 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,
@@ -239,104 +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 {
-      await writeMigrationPackage(packageDir, manifest, []);
-      await scaffoldMigrationTs(packageDir, {
-        descriptors: descriptorResult.descriptors,
-        contractJsonPath: contractPathAbsolute,
-      });
-
-      // Always run emit inline; structured errors thrown during evaluation
-      // (e.g. invalid migration.ts shape, missing file) propagate through
-      // emitMigration to the CLI envelope.
-      const { operations, migrationId } = await emitMigration(packageDir, {
-        targetId: config.target.targetId,
-        migrations,
-        frameworkComponents,
-      });
-
-      const sql = extractSqlDdl(operations);
-      const result: MigrationPlanResult = {
-        ok: true,
-        noOp: false,
-        from: fromHash,
-        to: toStorageHash,
-        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 },
-      };
-      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/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') {

package/src/lib/migration-emit.ts

@@ -1,23 +1,32 @@
 /**
- * Shared helper for emitting `ops.json` from a migration package's
- * `migration.ts`.
+ * Shared helper for emitting `ops.json` and attesting `migration.json` for a
+ * migration package's `migration.ts`.
  *
  * Two flows are dispatched here:
- *  - Descriptor flow (Postgres): the framework evaluates `migration.ts` (which
- *    re-exports the planner's descriptor list), calls the target's
- *    `resolveDescriptors` to produce display-oriented operations, and writes
- *    `ops.json` + `manifest.json`.
- *  - Class flow (Mongo): the target owns the source-loading and ops
- *    serialization step via its `emit` capability. The capability
- *    dynamic-imports `migration.ts`, invokes its class to produce
- *    operations, and calls `writeMigrationOps`. The framework helper
- *    then attests the package (single source of truth for
- *    `migrationId`).
+ *  - Descriptor flow (Postgres): the framework evaluates `migration.ts`
+ *    (which re-exports the planner's descriptor list), calls the target's
+ *    `resolveDescriptors` to produce display-oriented operations, writes
+ *    `ops.json`, and attests `migration.json`.
+ *  - Class flow (Mongo): the target's `emit` capability dynamic-imports
+ *    `migration.ts`, instantiates the default-exported `Migration` subclass
+ *    (or invokes the default-exported factory function), reads `operations`,
+ *    and writes `ops.json`. This helper then attests `migration.json` once
+ *    the capability returns.
+ *
+ * In both cases attestation is owned by this helper so the on-disk artifacts
+ * are guaranteed to be fully attested when emit returns.
+ *
+ * Note that this helper is the CLI-driven emit path. Class-flow `migration.ts`
+ * files are also self-emitting via `Migration.run(...)` when run directly;
+ * that path attests inside `Migration.run` and produces byte-identical
+ * artifacts. This helper exists primarily to bridge descriptor-flow targets
+ * and to give `migration plan` a single in-process emit dispatch.
  *
  * Used by `migration emit` (always) and `migration plan` (always, after
  * scaffolding `migration.ts`). Both flows run in-process so that structured
- * errors thrown during evaluation propagate as real exceptions and the
- * CLI's error envelope renders them with full structured metadata.
+ * errors thrown during evaluation (notably `errorUnfilledPlaceholder` with
+ * code `PN-MIG-2001`) propagate as real exceptions and the CLI's error
+ * envelope renders them with full structured metadata.
  */
 
 import assert from 'node:assert/strict';
@@ -31,6 +40,7 @@ import { attestMigration } from '@prisma-next/migration-tools/attestation';
 import { readMigrationPackage, writeMigrationOps } from '@prisma-next/migration-tools/io';
 import { evaluateMigrationTs, hasMigrationTs } from '@prisma-next/migration-tools/migration-ts';
 import { errorMigrationFileMissing, errorTargetMigrationNotSupported } from '../utils/cli-errors';
+import { migrationStrategy } from './migration-strategy';
 
 /**
  * Context passed to `emitMigration`. Captures everything the helper needs to
@@ -45,7 +55,7 @@ export interface EmitMigrationContext {
 /**
  * Result of a successful emit: the operations that were written to `ops.json`
  * (display-oriented shape) and the content-addressed migrationId persisted to
- * `manifest.json`.
+ * `migration.json`.
  */
 export interface EmitMigrationResult {
   readonly operations: readonly MigrationPlanOperation[];
@@ -68,22 +78,24 @@ export async function emitMigration(
     throw errorMigrationFileMissing(dir);
   }
 
-  if (ctx.migrations.resolveDescriptors) {
+  const strategy = migrationStrategy(ctx.migrations, ctx.targetId);
+
+  if (strategy === 'descriptor') {
     return emitDescriptorFlow(dir, ctx.migrations, ctx);
   }
 
-  if (ctx.migrations.emit) {
-    const operations = await ctx.migrations.emit({
-      dir,
-      frameworkComponents: ctx.frameworkComponents,
+  if (!ctx.migrations.emit) {
+    throw errorTargetMigrationNotSupported({
+      why: `Target "${ctx.targetId}" does not implement the class-flow \`emit\` capability; cannot emit a migration package`,
     });
-    const migrationId = await attestMigration(dir);
-    return { operations, migrationId };
   }
 
-  throw errorTargetMigrationNotSupported({
-    why: `Target "${ctx.targetId}" does not implement resolveDescriptors or emit; cannot emit a migration package`,
+  const operations = await ctx.migrations.emit({
+    dir,
+    frameworkComponents: ctx.frameworkComponents,
   });
+  const migrationId = await attestMigration(dir);
+  return { operations, migrationId };
 }
 
 /**

package/src/lib/migration-strategy.ts

@@ -0,0 +1,49 @@
+/**
+ * Migration authoring strategy selector.
+ *
+ * Targets currently use one of two strategies to author `migration.ts`:
+ *
+ *  - **Descriptor flow** — the planner produces an `OperationDescriptor[]`
+ *    and `migration.ts` is a `export default () => [...]` file that the CLI
+ *    later replays through `resolveDescriptors` at emit time. Postgres uses
+ *    this today.
+ *  - **Class flow** — the planner produces a `MigrationPlanWithAuthoringSurface`
+ *    that renders itself as a `class M extends Migration { ... }` file. The
+ *    CLI dispatches to the target's `emit` capability at emit time. Mongo
+ *    uses this today.
+ *
+ * The two are mutually exclusive at the target level: a migrations capability
+ * either implements the descriptor-flow trio (`planWithDescriptors`,
+ * `resolveDescriptors`, `renderDescriptorTypeScript`) or the class-flow
+ * `emit` hook. `migrationStrategy` discriminates between them by observing
+ * which hooks are present, and is consumed by `migration new`, `migration
+ * plan`, and `migration emit` to keep strategy-specific branching in one
+ * place.
+ */
+
+import { errorTargetHasIncompleteMigrationCapabilities } from '@prisma-next/errors/migration';
+import type { TargetMigrationsCapability } from '@prisma-next/framework-components/control';
+
+export type MigrationStrategy = 'descriptor' | 'class-based';
+
+/**
+ * Determine which authoring strategy a target uses, based on the shape of
+ * its `TargetMigrationsCapability`. Callers that need strategy-specific
+ * guarantees (e.g. that `resolveDescriptors` is present) should narrow on
+ * the returned tag and trust the capability fields directly rather than
+ * re-probing.
+ *
+ * Throws `errorTargetHasIncompleteMigrationCapabilities` (PN-MIG-2011) when
+ * the capability registers neither flow. We diagnose this here rather than
+ * deferring to the dispatch site so a misconfigured target gets an honest
+ * "incomplete capability" error instead of being silently routed to one
+ * flow and reported as missing the *other* flow's hook.
+ */
+export function migrationStrategy(
+  migrations: TargetMigrationsCapability,
+  targetId: string,
+): MigrationStrategy {
+  if (migrations.resolveDescriptors) return 'descriptor';
+  if (migrations.emit) return 'class-based';
+  throw errorTargetHasIncompleteMigrationCapabilities({ targetId });
+}

package/src/utils/cli-errors.ts

@@ -34,4 +34,6 @@ export {
   errorMigrationFileMissing,
   errorMigrationInvalidDefaultExport,
   errorMigrationPlanNotArray,
+  errorUnfilledPlaceholder,
+  placeholder,
 } from '@prisma-next/errors/migration';