@prisma-next/cli 0.16.0-dev.3 → 0.16.0-dev.30

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

@@ -2,7 +2,7 @@ import { materialiseExtensionMigrationPackageIfMissing } from '@prisma-next/migr
 import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
 import type { MigrationOps } from '@prisma-next/migration-tools/package';
 import {
-  emitContractSpaceArtefacts,
+  emitContractSpaceArtifacts,
   planAllSpaces,
   readContractSpaceHeadRef,
   type SpacePlanOutput,
@@ -39,7 +39,7 @@ export interface SeedPhaseExtensionInput {
 
 export interface ContractSpaceSeedPhaseInputs {
   readonly migrationsDir: string;
-  readonly extensionPacks: ReadonlyArray<SeedPhaseExtensionInput>;
+  readonly extensions: ReadonlyArray<SeedPhaseExtensionInput>;
 }
 
 /**
@@ -53,7 +53,7 @@ export interface ContractSpaceSeedPhaseInputs {
  * - `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`,
+ * Either way, the artifacts (`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.
  */
@@ -75,9 +75,11 @@ export interface ContractSpaceSeedPhaseResult {
  * 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.
+ * 2. Write the head contract into the migrations-root snapshot store
+ *    (write-if-absent, keyed by hash) and unconditionally re-emit
+ *    `refs/head.json`, via {@link emitContractSpaceArtifacts}. The
+ *    framework owns `refs/head.json`; re-emit is the contract for that
+ *    file. The snapshot itself is only written once per distinct hash.
  * 3. Materialise any descriptor-shipped migration packages not yet on
  *    disk via {@link materialiseExtensionMigrationPackageIfMissing}.
  *    Existing packages are left untouched (by-existence skip).
@@ -96,7 +98,7 @@ export interface ContractSpaceSeedPhaseResult {
 export async function runContractSpaceSeedPhase(
   inputs: ContractSpaceSeedPhaseInputs,
 ): Promise<ContractSpaceSeedPhaseResult> {
-  const planInputs = inputs.extensionPacks
+  const planInputs = inputs.extensions
     .filter(
       (
         pack,
@@ -132,7 +134,7 @@ export async function runContractSpaceSeedPhase(
     string,
     NonNullable<SeedPhaseExtensionInput['contractSpace']>
   >();
-  for (const pack of inputs.extensionPacks) {
+  for (const pack of inputs.extensions) {
     if (pack.contractSpace !== undefined) descriptorBySpace.set(pack.id, pack.contractSpace);
   }
 
@@ -144,7 +146,7 @@ export async function runContractSpaceSeedPhase(
     const onDiskHeadRef = await readContractSpaceHeadRef(inputs.migrationsDir, space.spaceId);
     const priorHash = onDiskHeadRef?.hash ?? null;
 
-    await emitContractSpaceArtefacts(inputs.migrationsDir, space.spaceId, {
+    await emitContractSpaceArtifacts(inputs.migrationsDir, space.spaceId, {
       contract: descriptor.contractJson,
       contractDts: buildPlaceholderContractDts(space.spaceId),
       headRef: { hash: descriptor.headRef.hash, invariants: descriptor.headRef.invariants },

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

@@ -1,5 +1,5 @@
 /**
- * Single descriptor-import boundary for CLI consumers of `Config.extensionPacks`.
+ * Single descriptor-import boundary for CLI consumers of `Config.extensions`.
  *
  * Every CLI command / utility that reads an extension descriptor's
  * `contractSpace` projection (loader, migrate-pass, extension-migrations
@@ -54,9 +54,9 @@ export interface ExtensionPackInput {
 }
 
 /**
- * Structural shape we read off each `Config.extensionPacks` entry.
+ * Structural shape we read off each `Config.extensions` entry.
  *
- * The CLI is the descriptor-import boundary; `extensionPacks` is the only
+ * The CLI is the descriptor-import boundary; `extensions` 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
@@ -76,14 +76,14 @@ type ExtensionPackLike = {
 };
 
 /**
- * Project the CLI's `Config.extensionPacks` array into the canonical
+ * Project the CLI's `Config.extensions` 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>,
+  extensions: ReadonlyArray<unknown>,
 ): readonly ExtensionPackInput[] {
-  return extensionPacks.map((raw) => {
+  return extensions.map((raw) => {
     const pack = raw as ExtensionPackLike;
     if (pack.contractSpace === undefined) {
       return { id: pack.id, targetId: pack.targetId };
@@ -147,10 +147,10 @@ export function toDeclaredExtensions(
  * always reads the contract from on-disk artefacts instead.
  */
 export function toDeclaredExtensionsFromRaw(
-  extensionPacks: ReadonlyArray<unknown>,
+  extensions: ReadonlyArray<unknown>,
 ): readonly DeclaredExtensionEntry[] {
   const entries: DeclaredExtensionEntry[] = [];
-  for (const raw of extensionPacks) {
+  for (const raw of extensions) {
     if (typeof raw !== 'object' || raw === null) continue;
     const descriptor = Object.getOwnPropertyDescriptor(raw, 'contractSpace');
     if (descriptor === undefined) continue;

package/src/utils/formatters/migration-graph-labels.ts

@@ -104,8 +104,7 @@ function abbreviateHash(hash: string, hashLength: number, emptySource: string):
   if (hash === EMPTY_CONTRACT_HASH) {
     return emptySource;
   }
-  const stripped = hash.startsWith('sha256:') ? hash.slice(7) : hash;
-  return stripped.slice(0, hashLength);
+  return hash.slice(0, hashLength);
 }
 
 interface ContractOverlayNames {

package/src/utils/formatters/migration-list-data-column.ts

@@ -18,8 +18,7 @@ export function migrationListEmptySource(glyphMode: GlyphMode): string {
 }
 
 export function abbreviateContractHash(hash: string): string {
-  const stripped = hash.startsWith('sha256:') ? hash.slice(7) : hash;
-  return stripped.slice(0, MIGRATION_LIST_HASH_WIDTH);
+  return hash.slice(0, MIGRATION_LIST_HASH_WIDTH);
 }
 
 export function padFromHashColumn(text: string, width: number): string {

package/src/utils/framework-components.ts

@@ -4,7 +4,7 @@ import {
   type TargetBoundComponentDescriptor,
 } from '@prisma-next/framework-components/components';
 import type { ControlStack } from '@prisma-next/framework-components/control';
-import { errorConfigValidation, errorContractMissingExtensionPacks } from './cli-errors';
+import { errorConfigValidation, errorContractMissingExtensions } from './cli-errors';
 
 /**
  * Asserts that all framework components are compatible with the expected family and target.
@@ -27,7 +27,7 @@ import { errorConfigValidation, errorContractMissingExtensionPacks } from './cli
  * @example
  * ```ts
  * const config = await loadConfig();
- * const frameworkComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
+ * const frameworkComponents = [config.target, config.adapter, ...(config.extensions ?? [])];
  *
  * // Validate and type-narrow components before passing to planner
  * const typedComponents = assertFrameworkComponentsCompatible(
@@ -114,12 +114,12 @@ export function assertFrameworkComponentsCompatible<
  * This check ensures the emitted contract matches the CLI config before running
  * commands that depend on the contract (e.g., db verify, db sign).
  *
- * @param contract - The contract to validate (must include targetFamily, target, extensionPacks).
- * @param stack - The control plane stack (target, adapter, driver, extensionPacks).
+ * @param contract - The contract to validate (must include targetFamily, target, extensions).
+ * @param stack - The control plane stack (target, adapter, driver, extensions).
  *
  * @throws {CliStructuredError} errorConfigValidation when contract.targetFamily or contract.target
  *   doesn't match the configured family/target.
- * @throws {CliStructuredError} errorContractMissingExtensionPacks when the contract requires
+ * @throws {CliStructuredError} errorContractMissingExtensions when the contract requires
  *   extension packs that are not provided in the config (includes all missing packs in error.meta).
  *
  * @example
@@ -141,14 +141,14 @@ export function assertContractRequirementsSatisfied<
   contract,
   stack,
 }: {
-  readonly contract: Pick<Contract, 'targetFamily' | 'target' | 'extensionPacks'>;
+  readonly contract: Pick<Contract, 'targetFamily' | 'target' | 'extensions'>;
   readonly stack: ControlStack<TFamilyId, TTargetId>;
 }): void {
   const providedComponentIds = new Set<string>([
     stack.target.id,
     ...(stack.adapter ? [stack.adapter.id] : []),
   ]);
-  for (const extension of stack.extensionPacks) {
+  for (const extension of stack.extensions) {
     providedComponentIds.add(extension.id);
   }
 
@@ -172,8 +172,8 @@ export function assertContractRequirementsSatisfied<
   }
 
   if (result.missingExtensionPackIds.length > 0) {
-    throw errorContractMissingExtensionPacks({
-      missingExtensionPacks: result.missingExtensionPackIds,
+    throw errorContractMissingExtensions({
+      missingExtensions: result.missingExtensionPackIds,
       providedComponentIds: [...providedComponentIds],
     });
   }

package/src/utils/integrity-violation-to-check-failure.ts

@@ -69,15 +69,15 @@ export function integrityViolationToCheckFailure(
         code: 'MIGRATION.CHECK_ORPHAN_SPACE_DIR',
         where: spaceRelative(violation.spaceId),
         why: `Contract-space directory "${violation.spaceId}" exists on disk but no extension declares it.`,
-        fix: 'Remove the orphan directory, or declare the extension in `extensionPacks`.',
+        fix: 'Remove the orphan directory, or declare the extension in `extensions`.',
       };
     case 'declaredButUnmigrated':
       return {
         space: violation.spaceId,
         code: 'MIGRATION.CHECK_DECLARED_BUT_UNMIGRATED',
         where: spaceRelative(violation.spaceId),
-        why: `Extension "${violation.spaceId}" is declared in \`extensionPacks\` but has no on-disk migrations directory.`,
-        fix: 'Re-emit the extension contract-space artefacts with `prisma-next contract emit` and migration planning, or remove the extension from `extensionPacks` if it is unused.',
+        why: `Extension "${violation.spaceId}" is declared in \`extensions\` but has no on-disk migrations directory.`,
+        fix: 'Re-emit the extension contract-space artefacts with `prisma-next contract emit` and migration planning, or remove the extension from `extensions` if it is unused.',
       };
     case 'headRefMissing':
       return {

package/src/utils/migration-command-scaffold.ts

@@ -154,7 +154,7 @@ export async function prepareMigrationContext(
     target: config.target,
     adapter: config.adapter,
     driver: config.driver,
-    extensionPacks: config.extensionPacks ?? [],
+    extensions: config.extensions ?? [],
   });
 
   // Create progress adapter

package/src/utils/plan-resolution.ts

@@ -19,7 +19,7 @@ import {
 } from './cli-errors';
 import { mapContractAtError } from './contract-at-errors';
 
-const FULL_HASH_PATTERN = /^sha256:([0-9a-f]{64}|empty)$/;
+const FULL_HASH_PATTERN = /^([0-9a-f]{64}|empty)$/;
 
 export function looksLikeFullHash(input: string): boolean {
   return FULL_HASH_PATTERN.test(input);
@@ -27,9 +27,9 @@ export function looksLikeFullHash(input: string): boolean {
 
 export type FromResolution =
   | { kind: 'greenfield'; fromHash: null; fromContract: null }
-  | { kind: 'graph-node'; fromHash: string; fromContract: Contract; sourceDir: string }
+  | { kind: 'graph-node'; fromHash: string; fromContract: Contract }
   | {
-      kind: 'snapshot';
+      kind: 'ref';
       fromHash: string;
       fromContract: Contract;
       contractDts: string;
@@ -81,7 +81,7 @@ export function assertFromIsGraphNode(
 
 type RefContractResolution =
   | {
-      kind: 'snapshot';
+      kind: 'ref';
       hash: string;
       contract: Contract;
       contractJson: unknown;
@@ -93,7 +93,6 @@ type RefContractResolution =
       contract: Contract;
       contractJson: unknown;
       contractDts: string;
-      sourceDir: string;
     };
 
 async function resolveContractRef(
@@ -107,9 +106,9 @@ async function resolveContractRef(
   try {
     const at = await space.contractAt(hash, refName !== undefined ? { refName } : undefined);
 
-    if (at.provenance === 'snapshot') {
+    if (at.provenance === 'ref') {
       return ok({
-        kind: 'snapshot',
+        kind: 'ref',
         hash: at.hash,
         contract: at.contract,
         contractJson: at.contractJson,
@@ -123,7 +122,6 @@ async function resolveContractRef(
       contract: at.contract,
       contractJson: at.contractJson,
       contractDts: at.contractDts,
-      sourceDir: at.sourceDir,
     });
   } catch (error) {
     return mapContractAtError(
@@ -152,7 +150,6 @@ async function resolveFromPolicy(
       kind: 'graph-node',
       fromHash: resolution.value.hash,
       fromContract: resolution.value.contract,
-      sourceDir: resolution.value.sourceDir,
     });
   }
 
@@ -178,7 +175,7 @@ async function resolveFromPolicy(
     throw error;
   }
   return ok({
-    kind: 'snapshot',
+    kind: 'ref',
     fromHash: hash,
     fromContract: contract,
     contractDts,

package/src/utils/ref-advancement.ts

@@ -1,8 +1,14 @@
 import { readFile } from 'node:fs/promises';
-import type { ContractIR } from '@prisma-next/migration-tools/refs';
-import { writeRefPaired } from '@prisma-next/migration-tools/refs';
+import { writeContractSnapshot } from '@prisma-next/migration-tools/contract-snapshot-store';
+import { errorInvalidRefName } from '@prisma-next/migration-tools/errors';
+import { validateRefName, writeRef } from '@prisma-next/migration-tools/refs';
 import { ifDefined } from '@prisma-next/utils/defined';
 
+export interface ContractIR {
+  readonly contract: unknown;
+  readonly contractDts: string;
+}
+
 export interface RefAdvancementFields {
   readonly advancedRef: { readonly name: string; readonly hash: string } | null;
   readonly plannedAdvanceRef: { readonly name: string; readonly hash: string } | null;
@@ -32,11 +38,22 @@ export async function readContractIR(
 
 export async function executeRefAdvancement(
   refsDir: string,
+  migrationsDir: string,
   name: string,
   hash: string,
   contractIR: ContractIR,
 ): Promise<{ name: string; hash: string }> {
-  await writeRefPaired(refsDir, name, { hash, invariants: [] }, contractIR);
+  // Validate the ref name before writing anything: writeRef validates it too,
+  // but only after the store write below, which would otherwise leave a
+  // (harmless, but pointless) orphan store entry on an invalid name.
+  if (!validateRefName(name)) {
+    throw errorInvalidRefName(name);
+  }
+  await writeContractSnapshot(migrationsDir, hash, {
+    contractJson: contractIR.contract,
+    contractDts: contractIR.contractDts,
+  });
+  await writeRef(refsDir, name, { hash, invariants: [] });
   return { name, hash };
 }
 
@@ -44,6 +61,7 @@ export async function buildRefAdvancementFields(options: {
   readonly advanceRef?: string;
   readonly db?: string;
   readonly refsDir: string;
+  readonly migrationsDir: string;
   readonly contractIR: ContractIR;
   readonly mode: 'plan' | 'apply';
   readonly hash: string;
@@ -60,6 +78,7 @@ export async function buildRefAdvancementFields(options: {
   }
   const advancedRef = await executeRefAdvancement(
     options.refsDir,
+    options.migrationsDir,
     name,
     options.hash,
     options.contractIR,