@prisma-next/cli 0.5.0 → 0.5.1

package/src/utils/contract-space-seed-phase.ts

@@ -0,0 +1,201 @@
+import { materialiseExtensionMigrationPackageIfMissing } from '@prisma-next/migration-tools/io';
+import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
+import type { MigrationOps } from '@prisma-next/migration-tools/package';
+import {
+  emitContractSpaceArtefacts,
+  planAllSpaces,
+  readContractSpaceHeadRef,
+  type SpacePlanOutput,
+  spaceMigrationDirectory,
+} from '@prisma-next/migration-tools/spaces';
+
+/**
+ * In-memory authored migration package shipped by an extension descriptor.
+ * Mirrors `MigrationPackage` from `@prisma-next/migration-tools/io` (the
+ * on-disk shape minus `dirPath`); redeclared structurally here so the
+ * CLI helper does not couple to any family's `ExtensionMigrationPackage`
+ * type — any family that ships pre-built migration packages can pass
+ * them through unchanged.
+ */
+export interface DescriptorMigrationPackage {
+  readonly dirName: string;
+  readonly metadata: MigrationMetadata;
+  readonly ops: MigrationOps;
+}
+
+/**
+ * Minimal descriptor view consumed by the seed phase. Mirrors the shape
+ * the SQL family ships on each declared extension entry; only the fields
+ * the seed phase needs are surfaced.
+ */
+export interface SeedPhaseExtensionInput {
+  readonly id: string;
+  readonly contractSpace?: {
+    readonly contractJson: unknown;
+    readonly headRef: { readonly hash: string; readonly invariants: readonly string[] };
+    readonly migrations: readonly DescriptorMigrationPackage[];
+  };
+}
+
+export interface ContractSpaceSeedPhaseInputs {
+  readonly migrationsDir: string;
+  readonly extensionPacks: ReadonlyArray<SeedPhaseExtensionInput>;
+}
+
+/**
+ * One per-space record describing what the seed phase did for an
+ * extension contract space. Surfaced verbatim by the caller (typically
+ * `migration plan`) so users see a single line per touched extension.
+ *
+ * - `action: 'updated'` — either the on-disk head pointer changed, or
+ *   one or more new descriptor-shipped migration packages were
+ *   materialised into `migrations/<spaceId>/<dirName>/`.
+ * - `action: 'unchanged'` — the on-disk head already matched the
+ *   descriptor and no new migration packages needed to be written.
+ *
+ * Either way, the artefacts (`contract.json`, `contract.d.ts`,
+ * `refs/head.json`) are re-emitted: the framework owns those files and
+ * makes the re-emit observably idempotent at the byte level.
+ */
+export interface ContractSpaceSeedPhaseRecord {
+  readonly spaceId: string;
+  readonly action: 'updated' | 'unchanged';
+  readonly priorHash: string | null;
+  readonly newHash: string;
+  readonly newMigrationDirs: readonly string[];
+}
+
+export interface ContractSpaceSeedPhaseResult {
+  readonly seeded: readonly ContractSpaceSeedPhaseRecord[];
+}
+
+/**
+ * Phase-1 of the two-phase `migration plan` pipeline (sub-spec § 4).
+ *
+ * For every extension that exposes a `contractSpace`:
+ *
+ * 1. Read the on-disk head ref (returns `null` on first emit).
+ * 2. Re-emit `contract.json` / `contract.d.ts` / `refs/head.json`
+ *    unconditionally via {@link emitContractSpaceArtefacts}. The
+ *    framework owns these files; re-emit is the contract.
+ * 3. Materialise any descriptor-shipped migration packages not yet on
+ *    disk via {@link materialiseExtensionMigrationPackageIfMissing}.
+ *    Existing packages are left untouched (by-existence skip).
+ *
+ * The return value lets the caller render a per-space status line and
+ * lets the phase-2 aggregate loader run on a now-consistent disk state
+ * (every loaded extension is guaranteed to have its head ref pinned
+ * to the descriptor's hash and to ship every package the descriptor
+ * declares).
+ *
+ * Output ordering is deterministic and alphabetical by spaceId (via
+ * {@link planAllSpaces}, which also detects duplicate spaceIds). This
+ * matches the canonical sort order used by every other aggregate
+ * surface (`migration apply`, `migration status`, the runner).
+ */
+export async function runContractSpaceSeedPhase(
+  inputs: ContractSpaceSeedPhaseInputs,
+): Promise<ContractSpaceSeedPhaseResult> {
+  const planInputs = inputs.extensionPacks
+    .filter(
+      (
+        pack,
+      ): pack is SeedPhaseExtensionInput & {
+        contractSpace: NonNullable<SeedPhaseExtensionInput['contractSpace']>;
+      } => pack.contractSpace !== undefined,
+    )
+    .map((pack) => ({
+      spaceId: pack.id,
+      priorContract: null,
+      newContract: pack.contractSpace.contractJson,
+      __pack: pack.contractSpace,
+    }));
+
+  // `planAllSpaces` brings deterministic alphabetical ordering and
+  // duplicate-spaceId detection. The "planner" callback is a no-op
+  // pass-through that simply returns the descriptor's pre-built
+  // migration packages.
+  const planned: readonly SpacePlanOutput<DescriptorMigrationPackage>[] = planAllSpaces(
+    planInputs,
+    (input) =>
+      (
+        input as typeof input & {
+          readonly __pack: NonNullable<SeedPhaseExtensionInput['contractSpace']>;
+        }
+      ).__pack.migrations,
+  );
+
+  // Reassemble a spaceId → descriptor lookup so the loop below can read
+  // the contractJson / headRef without leaking the typed-cast back into
+  // `planAllSpaces`'s output shape.
+  const descriptorBySpace = new Map<
+    string,
+    NonNullable<SeedPhaseExtensionInput['contractSpace']>
+  >();
+  for (const pack of inputs.extensionPacks) {
+    if (pack.contractSpace !== undefined) descriptorBySpace.set(pack.id, pack.contractSpace);
+  }
+
+  const seeded: ContractSpaceSeedPhaseRecord[] = [];
+  for (const space of planned) {
+    const descriptor = descriptorBySpace.get(space.spaceId);
+    if (descriptor === undefined) continue;
+
+    const onDiskHeadRef = await readContractSpaceHeadRef(inputs.migrationsDir, space.spaceId);
+    const priorHash = onDiskHeadRef?.hash ?? null;
+
+    await emitContractSpaceArtefacts(inputs.migrationsDir, space.spaceId, {
+      contract: descriptor.contractJson,
+      contractDts: buildPlaceholderContractDts(space.spaceId),
+      headRef: { hash: descriptor.headRef.hash, invariants: descriptor.headRef.invariants },
+    });
+
+    const spaceDir = spaceMigrationDirectory(inputs.migrationsDir, space.spaceId);
+    const newMigrationDirs: string[] = [];
+    for (const pkg of space.migrationPackages) {
+      const { written } = await materialiseExtensionMigrationPackageIfMissing(spaceDir, pkg);
+      if (written) newMigrationDirs.push(pkg.dirName);
+    }
+
+    const action: ContractSpaceSeedPhaseRecord['action'] =
+      priorHash !== descriptor.headRef.hash || newMigrationDirs.length > 0
+        ? 'updated'
+        : 'unchanged';
+
+    seeded.push({
+      spaceId: space.spaceId,
+      action,
+      priorHash,
+      newHash: descriptor.headRef.hash,
+      newMigrationDirs,
+    });
+  }
+
+  return { seeded };
+}
+
+/**
+ * Placeholder `.d.ts` content for an extension space's on-disk mirror.
+ *
+ * Rendering a fully-typed `.d.ts` for an extension contract requires
+ * the SQL-family renderer with the codec / typemap registry threaded
+ * through; until that integration ships, the on-disk `.d.ts` is a
+ * stub `export {};` module that documents how consumers should
+ * validate the sibling `contract.json`. The stub typechecks on its
+ * own and does not need any TypeScript suppressions.
+ */
+function buildPlaceholderContractDts(spaceId: string): string {
+  return [
+    '/**',
+    ` * Placeholder \`.d.ts\` for extension space "${spaceId}".`,
+    ' *',
+    ' * The framework re-emits this file on every `migration plan` run',
+    ' * alongside `contract.json` and `refs/head.json`. A typed `.d.ts`',
+    ' * rendering pass for extension contracts is tracked separately;',
+    ' * until that ships, consumers should import `contract.json`',
+    ' * directly with `validateContract<…>(…)`.',
+    ' */',
+    'export {};',
+    '',
+  ].join('\n');
+}

package/src/utils/extension-pack-inputs.ts

@@ -16,8 +16,6 @@
 import type { DeclaredExtensionEntry } from '@prisma-next/migration-tools/aggregate';
 import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
 import type { MigrationOps } from '@prisma-next/migration-tools/package';
-import type { ExtensionMigrationsExtensionInput } from './contract-space-extension-migrations-pass';
-import type { MigrateExtensionInput } from './contract-space-migrate-pass';
 
 /**
  * In-memory authored migration package shipped by an extension descriptor.
@@ -108,63 +106,57 @@ export function toExtensionInputs(
 // ---------------------------------------------------------------------------
 
 /**
- * Aggregate-loader projection: surfaces `targetId` + `contractSpace.contractJson`
- * to {@link import('./contract-space-aggregate-loader').buildContractSpaceAggregate}
- * and a `hashByContractJson` map keyed by the same `contractJson` reference
- * the loader hands to its hash callback.
+ * Aggregate-loader projection. Surfaces `id` + `targetId` per
+ * contract-space-bearing extension to
+ * {@link import('./contract-space-aggregate-loader').buildContractSpaceAggregate}.
+ *
+ * Codec-only extensions (no `contractSpace` declaration) are filtered
+ * out: they are not contract-space members, so the aggregate loader
+ * has nothing to do with them. Filtering happens at this descriptor-
+ * import boundary so the loader stays oblivious to that distinction —
+ * every entry it sees expects an on-disk `migrations/<id>/` directory.
  */
-export function toDeclaredExtensions(inputs: ReadonlyArray<ExtensionPackInput>): {
-  readonly entries: ReadonlyArray<DeclaredExtensionEntry>;
-  readonly hashByContractJson: Map<unknown, string>;
-} {
+export function toDeclaredExtensions(
+  inputs: ReadonlyArray<ExtensionPackInput>,
+): readonly DeclaredExtensionEntry[] {
   const entries: DeclaredExtensionEntry[] = [];
-  const hashByContractJson = new Map<unknown, string>();
   for (const pack of inputs) {
-    if (pack.contractSpace) {
-      entries.push({
-        id: pack.id,
-        targetId: pack.targetId,
-        contractSpace: { contractJson: pack.contractSpace.contractJson },
-      });
-      hashByContractJson.set(pack.contractSpace.contractJson, pack.contractSpace.headRef.hash);
-    } else {
-      entries.push({ id: pack.id, targetId: pack.targetId });
-    }
+    if (pack.contractSpace === undefined) continue;
+    entries.push({ id: pack.id, targetId: pack.targetId });
   }
-  return { entries, hashByContractJson };
+  return entries;
 }
 
-/** Migrate-time per-space pass projection. */
-export function toMigratePassInputs(
-  inputs: ReadonlyArray<ExtensionPackInput>,
-): readonly MigrateExtensionInput[] {
-  return inputs.map((pack) =>
-    pack.contractSpace
-      ? {
-          id: pack.id,
-          contractSpace: {
-            contractJson: pack.contractSpace.contractJson,
-            headRef: pack.contractSpace.headRef,
-          },
-        }
-      : { id: pack.id },
-  );
-}
-
-/** Extension-migrations materialisation pass projection. */
-export function toExtensionMigrationsInputs(
-  inputs: ReadonlyArray<ExtensionPackInput>,
-): readonly ExtensionMigrationsExtensionInput[] {
-  return inputs.map((pack) =>
-    pack.contractSpace
-      ? {
-          id: pack.id,
-          contractSpace: {
-            contractJson: pack.contractSpace.contractJson,
-            headRef: pack.contractSpace.headRef,
-            migrations: pack.contractSpace.migrations,
-          },
-        }
-      : { id: pack.id },
-  );
+/**
+ * Minimal aggregate-loader projection that extracts `id` + `targetId`
+ * from raw extension pack descriptors **without invoking any
+ * `contractSpace` accessor**. Inspects the own-property descriptor so
+ * that getter-backed `contractSpace` declarations are detected but
+ * never called.
+ *
+ * Inclusion semantics match {@link toDeclaredExtensions}: a data
+ * property whose value is explicitly `undefined` is treated as "no
+ * contract-space declaration" and skipped, mirroring the
+ * `pack.contractSpace === undefined` check used on canonicalised
+ * inputs. Prototype-chain `contractSpace` properties (no own
+ * descriptor) are also skipped.
+ *
+ * This variant must be used by `buildContractSpaceAggregate` so that
+ * the aggregate path (including `db verify`) never reads
+ * `contractSpace.contractJson` from extension descriptors — the loader
+ * always reads the contract from on-disk artefacts instead.
+ */
+export function toDeclaredExtensionsFromRaw(
+  extensionPacks: ReadonlyArray<unknown>,
+): readonly DeclaredExtensionEntry[] {
+  const entries: DeclaredExtensionEntry[] = [];
+  for (const raw of extensionPacks) {
+    if (typeof raw !== 'object' || raw === null) continue;
+    const descriptor = Object.getOwnPropertyDescriptor(raw, 'contractSpace');
+    if (descriptor === undefined) continue;
+    if ('value' in descriptor && descriptor.value === undefined) continue;
+    const pack = raw as { readonly id: string; readonly targetId: string };
+    entries.push({ id: pack.id, targetId: pack.targetId });
+  }
+  return entries;
 }

package/src/utils/formatters/migrations.ts

@@ -7,9 +7,9 @@ import { createColorFormatter, formatDim, isVerbose } from './helpers';
 
 /**
  * Render a single statement of an `OperationPreview` for the human-readable
- * preview block. SQL statements get a trailing `;` if missing — matches the
- * legacy `string[]`-based renderer byte-for-byte (per spec OQ-4). Other
- * languages (`'mongodb-shell'`) render verbatim.
+ * preview block. SQL statements get a trailing `;` if missing so the rendered
+ * preview is byte-identical to the legacy `string[]`-based renderer for SQL
+ * targets. Other languages (`'mongodb-shell'`) render verbatim.
  */
 function renderPreviewStatement(text: string, language: string): string | undefined {
   const trimmed = text.trim();
@@ -22,9 +22,10 @@ function renderPreviewStatement(text: string, language: string): string | undefi
 
 /**
  * Choose the header label for a preview block. SQL-only previews keep the
- * legacy `DDL preview` label (preserves CLI byte-identity for SQL targets per
- * spec OQ-4); previews from any other family — or a mix that includes any
- * non-SQL language — use the family-agnostic `Operation preview` label.
+ * legacy `DDL preview` label so the rendered output is byte-identical to the
+ * pre-aggregate SQL CLI; previews from any other family — or a mix that
+ * includes any non-SQL language — use the family-agnostic `Operation preview`
+ * label.
  *
  * An empty `statements` array deliberately renders as `Operation preview`
  * rather than `DDL preview`: `Array.prototype.every` is vacuously true for
@@ -76,8 +77,9 @@ export interface MigrationCommandResult {
   /**
    * Per-space execution breakdown in canonical schedule order
    * (extensions alphabetically, then app). Surfaces per-space markers
-   * + ops grouped by space; closes F1 / F4 / F7 from the M6
-   * verification doc. See {@link AggregatePerSpaceExecutionEntry}.
+   * and the ops grouped by space, so the CLI summary can name which
+   * space each op and marker belongs to instead of flattening them
+   * into a single ambiguous list. See {@link AggregatePerSpaceExecutionEntry}.
    */
   readonly perSpace?: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
   readonly summary: string;
@@ -88,10 +90,9 @@ export interface MigrationCommandResult {
 
 /**
  * Render the shared per-space execution block consumed by the `db init`
- * / `db update` / `migration apply` summaries (M6 sub-spec § Output
- * shape contract). Always shows: space label (`Extension space: <id>`
- * or `App space`) → per-op lines under each space → per-space marker
- * hash (when known).
+ * / `db update` / `migration apply` summaries. Always shows: space
+ * label (`Extension space: <id>` or `App space`) → per-op lines under
+ * each space → per-space marker hash (when known).
  *
  * `mode` controls the marker label phrasing — `'apply'` shows
  * `marker → <hash>` (post-apply), `'plan'` omits the marker line
@@ -165,7 +166,7 @@ export function formatMigrationPlanOutput(
   const formatYellow = createColorFormatter(useColor, yellow);
 
   // Per-space breakdown takes precedence over the flat ops tree when
-  // the aggregate flow surfaced one (M6 sub-spec § Output shape contract).
+  // the aggregate flow surfaced one.
   if (result.perSpace && result.perSpace.length > 0) {
     lines.push('');
     lines.push(...formatPerSpaceBlock(result.perSpace, 'plan', useColor));
@@ -294,7 +295,9 @@ export function formatMigrationApplyCommandOutput(
   return lines.join('\n');
 }
 
-interface MigrationShowResult {
+interface MigrationShowSpacePresent {
+  readonly kind: 'present';
+  readonly spaceId: string;
   readonly dirName: string;
   readonly dirPath: string;
   readonly from: string | null;
@@ -310,39 +313,48 @@ interface MigrationShowResult {
   readonly summary: string;
 }
 
-export function formatMigrationShowOutput(result: MigrationShowResult, flags: GlobalFlags): string {
-  if (flags.quiet) {
-    return '';
-  }
+interface MigrationShowSpaceMissing {
+  readonly kind: 'missing';
+  readonly spaceId: string;
+  readonly summary: string;
+}
 
-  const lines: string[] = [];
+type MigrationShowSpaceResult = MigrationShowSpacePresent | MigrationShowSpaceMissing;
 
-  const useColor = flags.color !== false;
+interface MigrationShowResult {
+  readonly spaces: readonly MigrationShowSpaceResult[];
+}
+
+function formatSpaceShowBlock(
+  space: MigrationShowSpacePresent,
+  useColor: boolean,
+): readonly string[] {
   const formatGreen = createColorFormatter(useColor, green);
   const formatYellow = createColorFormatter(useColor, yellow);
   const formatDimText = (text: string) => formatDim(useColor, text);
 
-  lines.push(`${formatGreen('✔')} ${result.dirName}`);
-  lines.push(`${formatDimText(`  from: ${result.from ?? '(baseline)'}`)}`);
-  lines.push(`${formatDimText(`  to:   ${result.to}`)}`);
-  lines.push(`${formatDimText(`  migrationHash: ${result.migrationHash}`)}`);
-  lines.push(`${formatDimText(`  created: ${result.createdAt}`)}`);
+  const lines: string[] = [];
+  lines.push(`${formatGreen('✔')} ${space.dirName}`);
+  lines.push(`${formatDimText(`  from: ${space.from ?? '(baseline)'}`)}`);
+  lines.push(`${formatDimText(`  to:   ${space.to}`)}`);
+  lines.push(`${formatDimText(`  migrationHash: ${space.migrationHash}`)}`);
+  lines.push(`${formatDimText(`  created: ${space.createdAt}`)}`);
 
   lines.push('');
-  lines.push(`${result.operations.length} operation(s)`);
+  lines.push(`${space.operations.length} operation(s)`);
 
-  if (result.operations.length > 0) {
+  if (space.operations.length > 0) {
     lines.push(`${formatDimText('│')}`);
-    for (let i = 0; i < result.operations.length; i++) {
-      const op = result.operations[i]!;
-      const isLast = i === result.operations.length - 1;
+    for (let i = 0; i < space.operations.length; i++) {
+      const op = space.operations[i]!;
+      const isLast = i === space.operations.length - 1;
       const treeChar = isLast ? '└' : '├';
       const destructiveMarker =
         op.operationClass === 'destructive' ? ` ${formatYellow('(destructive)')}` : '';
       lines.push(`${formatDimText(treeChar)}─ ${op.label}${destructiveMarker}`);
     }
 
-    const hasDestructive = result.operations.some((op) => op.operationClass === 'destructive');
+    const hasDestructive = space.operations.some((op) => op.operationClass === 'destructive');
     if (hasDestructive) {
       lines.push('');
       lines.push(
@@ -351,11 +363,11 @@ export function formatMigrationShowOutput(result: MigrationShowResult, flags: Gl
     }
   }
 
-  if (result.preview.statements.length > 0) {
+  if (space.preview.statements.length > 0) {
     lines.push('');
-    lines.push(`${formatDimText(previewBlockHeader(result.preview))}`);
+    lines.push(`${formatDimText(previewBlockHeader(space.preview))}`);
     lines.push('');
-    for (const statement of result.preview.statements) {
+    for (const statement of space.preview.statements) {
       const rendered = renderPreviewStatement(statement.text, statement.language);
       if (rendered) {
         lines.push(rendered);
@@ -363,6 +375,36 @@ export function formatMigrationShowOutput(result: MigrationShowResult, flags: Gl
     }
   }
 
+  return lines;
+}
+
+export function formatMigrationShowOutput(result: MigrationShowResult, flags: GlobalFlags): string {
+  if (flags.quiet) {
+    return '';
+  }
+
+  const useColor = flags.color !== false;
+  const formatDimText = (text: string) => formatDim(useColor, text);
+  const multipleSpaces = result.spaces.length > 1;
+  const lines: string[] = [];
+
+  for (let i = 0; i < result.spaces.length; i++) {
+    const space = result.spaces[i]!;
+    if (multipleSpaces) {
+      lines.push(formatDimText(`── ${space.spaceId} ──`));
+    }
+    if (space.kind === 'missing') {
+      lines.push(formatDimText(`  ${space.summary}`));
+    } else {
+      for (const line of formatSpaceShowBlock(space, useColor)) {
+        lines.push(line);
+      }
+    }
+    if (i < result.spaces.length - 1) {
+      lines.push('');
+    }
+  }
+
   return lines.join('\n');
 }
 
@@ -401,7 +443,7 @@ export function formatMigrationApplyOutput(
     }
 
     // Per-space breakdown — replaces the single ambiguous `Signature:`
-    // line per M6 sub-spec § Output shape contract / AC4 / AC5.
+    // line with a per-space marker + ops listing.
     if (result.perSpace && result.perSpace.length > 0) {
       lines.push('');
       lines.push(...formatPerSpaceBlock(result.perSpace, 'apply', useColor));
@@ -415,9 +457,9 @@ export function formatMigrationApplyOutput(
       );
     } else if (result.marker) {
       // Single-space fallback (no aggregate breakdown surfaced — e.g.
-      // older callers / non-aggregate code paths). Renamed from
-      // `Signature` to `App-space marker` per AC4 — when only one
-      // marker is observable, name what it covers explicitly.
+      // older callers / non-aggregate code paths). The label is
+      // `App-space marker` (not `Signature`) so that when only one
+      // marker is observable we still name what it covers explicitly.
       lines.push(`${formatDimText(`  App-space marker: ${result.marker.storageHash}`)}`);
       if (result.marker.profileHash) {
         lines.push(`${formatDimText(`  Profile hash: ${result.marker.profileHash}`)}`);