@prisma-next/cli 0.5.0-dev.9 → 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/emit-queue.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-output FIFO queue for `executeContractEmit`.
+ *
+ * Ensures that at most one emit (load → resolve source → emit bytes → publish)
+ * runs per output JSON path at a time. Concurrent calls for the same path
+ * line up behind the in-flight one and run in submission order; the user-visible
+ * outcome is "last submission wins on disk" without any supersession bookkeeping.
+ *
+ * Long-lived hosts (Vite dev server, watch CLIs) must call `disposeEmitQueue`
+ * when they stop publishing to a path, otherwise the module-global `Map`
+ * accumulates one entry per unique output path for the lifetime of the process.
+ */
+const emitQueues = new Map<string, Promise<unknown>>();
+
+export function queueEmitByOutput<T>(outputJsonPath: string, action: () => Promise<T>): Promise<T> {
+  const previous = emitQueues.get(outputJsonPath) ?? Promise.resolve();
+  // Continue regardless of the previous task's outcome — a failed emit must not
+  // block subsequent ones. The current task's outcome propagates via `next`.
+  const next = previous.then(action, action);
+  emitQueues.set(outputJsonPath, next);
+  return next;
+}
+
+export function disposeEmitQueue(outputJsonPath: string): void {
+  emitQueues.delete(outputJsonPath);
+}

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

@@ -0,0 +1,162 @@
+/**
+ * Single descriptor-import boundary for CLI consumers of `Config.extensionPacks`.
+ *
+ * Every CLI command / utility that reads an extension descriptor's
+ * `contractSpace` projection (loader, migrate-pass, extension-migrations
+ * pass, migration commands) goes through {@link toExtensionInputs}. The
+ * structural cast `pack as { contractSpace?: ... }` lives **only** here —
+ * downstream code consumes the canonical shape and maps it to its own
+ * narrower shape via the per-consumer adapters below.
+ *
+ * The CLI receives extension descriptors typed against the SQL family
+ * (or any other family in the future); this helper only depends on the
+ * structural shape of `contractSpace`. SQL-family callers pass the same
+ * `contractJson` / `headRef.hash` value through unchanged.
+ */
+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';
+
+/**
+ * In-memory authored migration package shipped by an extension descriptor.
+ * Mirrors the `MigrationPackage` shape from
+ * `@prisma-next/framework-components/control` minus `dirPath`; redeclared
+ * structurally here so the helper does not couple to the SQL family's
+ * `ExtensionMigrationPackage` type.
+ */
+export interface DescriptorMigrationPackage {
+  readonly dirName: string;
+  readonly metadata: MigrationMetadata;
+  readonly ops: MigrationOps;
+}
+
+/**
+ * The most-general projection of a single declared extension pack
+ * needed by the CLI's descriptor-import boundary.
+ *
+ * - `id` / `targetId` are always present.
+ * - `contractSpace` is present only when the extension declares one.
+ *   When present, it carries the canonical inputs every downstream
+ *   consumer needs — `contractJson`, `headRef`, and the descriptor's
+ *   pre-built migration packages.
+ */
+export interface ExtensionPackInput {
+  readonly id: string;
+  readonly targetId: string;
+  readonly contractSpace?: {
+    readonly contractJson: unknown;
+    readonly headRef: {
+      readonly hash: string;
+      readonly invariants: readonly string[];
+    };
+    readonly migrations: readonly DescriptorMigrationPackage[];
+  };
+}
+
+/**
+ * Structural shape we read off each `Config.extensionPacks` entry.
+ *
+ * The CLI is the descriptor-import boundary; `extensionPacks` is the only
+ * surface where the SQL-family-typed `ControlExtensionDescriptor` flows
+ * into framework-neutral helpers. The structural cast lives here, and
+ * here alone — every other CLI consumer reads the canonical
+ * {@link ExtensionPackInput} shape produced by {@link toExtensionInputs}.
+ */
+type ExtensionPackLike = {
+  readonly id: string;
+  readonly targetId: string;
+  readonly contractSpace?: {
+    readonly contractJson: unknown;
+    readonly headRef: {
+      readonly hash: string;
+      readonly invariants: readonly string[];
+    };
+    readonly migrations?: readonly DescriptorMigrationPackage[];
+  };
+};
+
+/**
+ * Project the CLI's `Config.extensionPacks` array into the canonical
+ * {@link ExtensionPackInput} shape. The single `as ExtensionPackLike`
+ * structural cast in the CLI lives inside this function.
+ */
+export function toExtensionInputs(
+  extensionPacks: ReadonlyArray<unknown>,
+): readonly ExtensionPackInput[] {
+  return extensionPacks.map((raw) => {
+    const pack = raw as ExtensionPackLike;
+    if (pack.contractSpace === undefined) {
+      return { id: pack.id, targetId: pack.targetId };
+    }
+    return {
+      id: pack.id,
+      targetId: pack.targetId,
+      contractSpace: {
+        contractJson: pack.contractSpace.contractJson,
+        headRef: pack.contractSpace.headRef,
+        migrations: pack.contractSpace.migrations ?? [],
+      },
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Per-consumer adapters: take the canonical `ExtensionPackInput[]` and
+// project to whatever narrower shape the downstream primitive needs.
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 DeclaredExtensionEntry[] {
+  const entries: DeclaredExtensionEntry[] = [];
+  for (const pack of inputs) {
+    if (pack.contractSpace === undefined) continue;
+    entries.push({ id: pack.id, targetId: pack.targetId });
+  }
+  return entries;
+}
+
+/**
+ * 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/graph-migration-mapper.ts

@@ -2,8 +2,8 @@
  * Maps MigrationGraph + status info to the generic graph renderer types.
  */
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
-import { findPath } from '@prisma-next/migration-tools/dag';
-import type { MigrationGraph } from '@prisma-next/migration-tools/types';
+import type { MigrationGraph } from '@prisma-next/migration-tools/graph';
+import { findPath } from '@prisma-next/migration-tools/migration-graph';
 import { ifDefined } from '@prisma-next/utils/defined';
 
 import type { StatusRef } from '../migration-types';
@@ -106,7 +106,11 @@ export function migrationGraphToRenderInput(input: MigrationGraphInput): Migrati
     for (const entry of entries) {
       const status = statusByDirName.get(entry.dirName);
       const icon = status ? STATUS_ICON[status] : '';
-      const label = `${entry.dirName}${icon}`;
+      const invariantsSuffix =
+        entry.invariants.length > 0
+          ? `  provides [${entry.invariants.map((id) => JSON.stringify(id)).join(', ')}]`
+          : '';
+      const label = `${entry.dirName}${icon}${invariantsSuffix}`;
 
       edgeList.push({
         from: toShortId(entry.from),