@prisma-next/cli 0.5.0-dev.9 → 0.5.0

package/src/utils/contract-space-migrate-pass.ts

@@ -0,0 +1,156 @@
+import {
+  detectSpaceContractDrift,
+  emitContractSpaceArtefacts,
+  readContractSpaceHeadRef,
+  type SpaceContractDriftResult,
+} from '@prisma-next/migration-tools/spaces';
+
+/**
+ * Minimal descriptor view consumed by the migrate-time per-space pass.
+ *
+ * The CLI receives descriptors typed against the SQL family (or any other
+ * family in the future); this helper only needs the structural shape of
+ * `contractSpace`, so it accepts an `unknown`-typed `contractJson` and
+ * a structurally-typed `headRef`. SQL-family callers pass the same
+ * `Contract<SqlStorage>` value through unchanged — `emitContractSpaceArtefacts`
+ * already serialises through `canonicalizeJson` and is framework-neutral.
+ *
+ * @see specs/framework-mechanism.spec.md § 3 — Per-space helper location.
+ */
+export interface MigrateExtensionInput {
+  readonly id: string;
+  readonly contractSpace?: {
+    readonly contractJson: unknown;
+    readonly headRef: { readonly hash: string; readonly invariants: readonly string[] };
+  };
+}
+
+/**
+ * Inputs needed to compose the migrate-time per-space pass at the CLI
+ * surface — typically called once after the app-space migration package
+ * has been written, regardless of whether the app-space had structural
+ * changes (an extension bump alone should still re-pin its artefacts).
+ */
+export interface ContractSpaceMigratePassInputs {
+  readonly migrationsDir: string;
+  readonly extensionPacks: ReadonlyArray<MigrateExtensionInput>;
+}
+
+export interface ContractSpaceMigratePassResult {
+  readonly drifts: readonly SpaceContractDriftResult[];
+  readonly emittedSpaceIds: readonly string[];
+}
+
+/**
+ * Run drift detection + on-disk artefact emission for every loaded
+ * extension space at `migrate` time.
+ *
+ * Per sub-spec § 3:
+ *
+ * - For each declared extension that exposes a `contractSpace`:
+ *   - Read the on-disk head hash from `migrations/<spaceId>/refs/head.json`
+ *     (returns `null` on first emit).
+ *   - Compare against the descriptor's `headRef.hash` via
+ *     `detectSpaceContractDrift`. The `kind` discriminant decides whether
+ *     the user sees a warning (`drift`), a no-op silent emit (`firstEmit`,
+ *     `noDrift`), or nothing at all.
+ *   - Always re-emit the on-disk artefacts (`contract.json`, `contract.d.ts`,
+ *     `refs/head.json`). The framework owns these files and the helper is
+ *     idempotent.
+ *
+ * Drift warnings are returned to the caller for formatting (TerminalUI,
+ * structured-output envelope, etc.) — the helper does not print directly,
+ * keeping it framework-neutral and unit-testable.
+ *
+ * Extension migration packages (the descriptor's pre-canned `migrations`
+ * array → `migrations/<spaceId>/<dirName>/`) are intentionally not
+ * materialised here — that interaction will be wired in a follow-on round
+ * once the runner-side single-tx slice (sub-spec § 6) is in place.
+ * On-disk artefacts are sufficient to lock the drift-warning behaviour
+ * and the always-on re-emit AC for R2.
+ *
+ * @see specs/framework-mechanism.spec.md § 3 — Drift detection (T1.9).
+ */
+export async function runContractSpaceMigratePass(
+  inputs: ContractSpaceMigratePassInputs,
+): Promise<ContractSpaceMigratePassResult> {
+  const drifts: SpaceContractDriftResult[] = [];
+  const emittedSpaceIds: string[] = [];
+
+  for (const pack of inputs.extensionPacks) {
+    if (pack.contractSpace === undefined) continue;
+    const { contractJson, headRef } = pack.contractSpace;
+
+    const onDiskHeadRef = await readContractSpaceHeadRef(inputs.migrationsDir, pack.id);
+    const drift = detectSpaceContractDrift(pack.id, {
+      descriptorHash: headRef.hash,
+      priorHeadHash: onDiskHeadRef?.hash ?? null,
+    });
+    drifts.push(drift);
+
+    await emitContractSpaceArtefacts(inputs.migrationsDir, pack.id, {
+      contract: contractJson,
+      contractDts: buildPlaceholderContractDts(pack.id),
+      headRef: { hash: headRef.hash, invariants: headRef.invariants },
+    });
+    emittedSpaceIds.push(pack.id);
+  }
+
+  return { drifts, emittedSpaceIds };
+}
+
+/**
+ * Format the user-facing drift warning for a single space. Callers
+ * funnel this through their preferred output channel (TerminalUI line,
+ * structured-output envelope `warnings[]`, etc.).
+ *
+ * Locks AM7 — drift warning surfaces the extension name and the diff
+ * direction (descriptor → on-disk head).
+ */
+export function formatContractSpaceDriftWarning(drift: SpaceContractDriftResult): string {
+  if (drift.kind !== 'drift') {
+    throw new Error(`formatContractSpaceDriftWarning called with non-drift result: ${drift.kind}`);
+  }
+  return (
+    `Contract-space drift detected for "${drift.spaceId}": descriptor hash ` +
+    `${drift.descriptorHash} differs from on-disk head hash ${drift.priorHeadHash ?? '<none>'}. ` +
+    `The on-disk artefacts under migrations/${drift.spaceId}/ will be refreshed to match the descriptor.`
+  );
+}
+
+/**
+ * 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; that integration is tracked under sub-spec Open Question 3
+ * (see `projects/extension-contract-spaces/specs/framework-mechanism.spec.md`).
+ *
+ * Until that ships, the on-disk `.d.ts` is a `@ts-nocheck` stub. The
+ * spec gap closing alongside the typed renderer is **AC2 / AC14**
+ * (byte-equivalence of per-space artefacts under `migrate`):
+ * a placeholder cannot be byte-equal to a fully-rendered `.d.ts` from
+ * the same descriptor, so AC2 / AC14 are PARTIAL today and become
+ * fully-PASS once OQ3 closes.
+ *
+ * Scheduled to close in **M3** (cipherstash editor tooling) — that's
+ * the milestone where the typed renderer gets its first real
+ * extension-space consumer and the byte-equivalence guarantee is
+ * practically required.
+ */
+function buildPlaceholderContractDts(spaceId: string): string {
+  return [
+    '// @ts-nocheck',
+    '/**',
+    ` * Placeholder \`.d.ts\` for extension space "${spaceId}".`,
+    ' *',
+    ' * The framework re-emits this file on every `migrate` run alongside',
+    ' * `contract.json` and `refs/head.json`. A typed `.d.ts` rendering',
+    " * pass for extension contracts is tracked under the project's open",
+    ' * questions; 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,170 @@
+/**
+ * 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';
+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.
+ * 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 `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.
+ */
+export function toDeclaredExtensions(inputs: ReadonlyArray<ExtensionPackInput>): {
+  readonly entries: ReadonlyArray<DeclaredExtensionEntry>;
+  readonly hashByContractJson: Map<unknown, string>;
+} {
+  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 });
+    }
+  }
+  return { entries, hashByContractJson };
+}
+
+/** 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 },
+  );
+}

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),