@prisma-next/cli 0.10.0 → 0.11.0-dev.10

package/src/utils/global-flags.ts

@@ -1,7 +1,17 @@
+import { notOk } from '@prisma-next/utils/result';
+import { CliStructuredError, errorInvalidOutputFormat, errorOutputFormatMutex } from './cli-errors';
+import { isCI } from './is-ci';
+import { handleResult } from './result-handler';
+import { createTerminalUI } from './terminal-ui';
+
+export type OutputFormat = 'pretty' | 'json';
+
 export interface GlobalFlags {
+  readonly format: OutputFormat;
+  readonly explicitFormat: boolean;
   readonly json?: boolean;
   readonly quiet?: boolean;
-  readonly verbose?: number; // 0, 1, or 2
+  readonly verbose?: number;
   readonly color?: boolean;
   readonly interactive?: boolean;
   readonly yes?: boolean;
@@ -12,6 +22,7 @@ export interface GlobalFlags {
  * Extend this for command-specific options instead of duplicating these fields.
  */
 export interface CommonCommandOptions {
+  readonly format?: string;
   readonly json?: string | boolean;
   readonly quiet?: boolean;
   readonly q?: boolean;
@@ -26,33 +37,117 @@ export interface CommonCommandOptions {
   readonly y?: boolean;
 }
 
+function isJsonFlagSet(json: string | boolean | undefined): boolean {
+  return json === true;
+}
+
+interface ResolvedOutputFormat {
+  readonly format: OutputFormat;
+  readonly explicitFormat: boolean;
+}
+
+function resolveOutputFormat(options: CommonCommandOptions): ResolvedOutputFormat {
+  const formatOption = options.format;
+  const jsonFlag = isJsonFlagSet(options.json);
+
+  if (formatOption !== undefined) {
+    if (formatOption !== 'pretty' && formatOption !== 'json') {
+      throw errorInvalidOutputFormat(formatOption);
+    }
+    if (jsonFlag && formatOption === 'pretty') {
+      throw errorOutputFormatMutex();
+    }
+    return { format: formatOption, explicitFormat: true };
+  }
+
+  if (jsonFlag) {
+    return { format: 'json', explicitFormat: false };
+  }
+
+  if (!process.stdout.isTTY) {
+    return { format: 'json', explicitFormat: false };
+  }
+
+  return { format: 'pretty', explicitFormat: false };
+}
+
+function inferJsonModeForParseError(options: CommonCommandOptions): boolean {
+  if (options.format === 'json') {
+    return true;
+  }
+  if (isJsonFlagSet(options.json) && options.format !== 'pretty') {
+    return true;
+  }
+  if (options.format !== undefined) {
+    return false;
+  }
+  return !process.stdout.isTTY;
+}
+
+function emitGlobalFlagParseError(error: CliStructuredError, options: CommonCommandOptions): never {
+  const jsonMode = inferJsonModeForParseError(options);
+  const flags: GlobalFlags = {
+    format: jsonMode ? 'json' : 'pretty',
+    explicitFormat: false,
+    ...(jsonMode ? { json: true } : {}),
+    color: false,
+    verbose: 0,
+    interactive: false,
+  };
+  const ui = createTerminalUI(flags);
+  const exitCode = handleResult(notOk(error), flags, ui);
+  process.exit(exitCode);
+}
+
+/**
+ * Parses global flags from CLI options.
+ * Handles verbosity flags (-v, --trace), output format (--format, --json),
+ * quiet mode, color, interactivity (--interactive/--no-interactive), and
+ * auto-accept (-y/--yes).
+ *
+ * On invalid or conflicting format flags, prints a structured CLI error
+ * envelope and exits with code 2.
+ */
+export function parseGlobalFlagsOrExit(options: CommonCommandOptions): GlobalFlags {
+  try {
+    return parseGlobalFlags(options);
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      emitGlobalFlagParseError(error, options);
+    }
+    throw error;
+  }
+}
+
 /**
  * Parses global flags from CLI options.
- * Handles verbosity flags (-v, --trace), JSON output, quiet mode, color,
- * interactivity (--interactive/--no-interactive), and auto-accept (-y/--yes).
+ * Handles verbosity flags (-v, --trace), output format (--format, --json),
+ * quiet mode, color, interactivity (--interactive/--no-interactive), and
+ * auto-accept (-y/--yes).
+ *
+ * Throws {@link CliStructuredError} for invalid or conflicting format flags.
  */
 export function parseGlobalFlags(options: CommonCommandOptions): GlobalFlags {
+  const { format, explicitFormat } = resolveOutputFormat(options);
   const flags: {
+    format: OutputFormat;
+    explicitFormat: boolean;
     json?: boolean;
     quiet?: boolean;
     verbose?: number;
     color?: boolean;
     interactive?: boolean;
     yes?: boolean;
-  } = {};
+  } = { format, explicitFormat };
 
-  // JSON output: explicit --json flag or auto-detect piped stdout (Unix convention)
-  if (options.json || !process.stdout.isTTY) {
+  if (format === 'json') {
     flags.json = true;
   }
 
-  // Quiet mode
   if (options.quiet || options.q) {
     flags.quiet = true;
   }
 
-  // Verbosity: -v = 1, --trace = 2
-  // Env toggles: PRISMA_NEXT_TRACE=1 ≅ --trace, PRISMA_NEXT_DEBUG=1 ≅ -v
   if (options.trace || process.env['PRISMA_NEXT_TRACE'] === '1') {
     flags.verbose = 2;
   } else if (options.verbose || options.v || process.env['PRISMA_NEXT_DEBUG'] === '1') {
@@ -61,8 +156,6 @@ export function parseGlobalFlags(options: CommonCommandOptions): GlobalFlags {
     flags.verbose = 0;
   }
 
-  // Color: respect NO_COLOR env var, --color/--no-color flags
-  // When JSON output is enabled, disable color to ensure clean JSON output
   if (process.env['NO_COLOR'] || flags.json) {
     flags.color = false;
   } else if (options['no-color']) {
@@ -70,12 +163,9 @@ export function parseGlobalFlags(options: CommonCommandOptions): GlobalFlags {
   } else if (options.color !== undefined) {
     flags.color = options.color;
   } else {
-    // Default: enable color if TTY
-    flags.color = process.stdout.isTTY && !process.env['CI'];
+    flags.color = process.stdout.isTTY && !isCI();
   }
 
-  // Interactivity: --interactive/--no-interactive
-  // Default: interactive when stdout is a TTY
   if (options['no-interactive']) {
     flags.interactive = false;
   } else if (options.interactive !== undefined) {
@@ -84,7 +174,6 @@ export function parseGlobalFlags(options: CommonCommandOptions): GlobalFlags {
     flags.interactive = !!process.stdout.isTTY;
   }
 
-  // Auto-accept prompts: -y/--yes
   if (options.yes || options.y) {
     flags.yes = true;
   }

package/src/utils/is-ci.ts

@@ -0,0 +1,18 @@
+import { isCI as ciInfoIsCI } from 'ci-info';
+
+/**
+ * Returns true when the process is running in any CI environment recognised
+ * by the `ci-info` package. The single source of truth for CI detection
+ * across this CLI — colour-output suppression and telemetry-skip both call
+ * this helper, so neither path drifts from the other when a new CI provider
+ * is added upstream.
+ *
+ * `ci-info` checks the standard `CI=true` marker plus dozens of
+ * provider-specific environment variables (Buildkite, Jenkins, Drone,
+ * Bitbucket Pipelines, Azure Pipelines, AWS CodeBuild, …) that the raw
+ * `process.env.CI` read misses.
+ *
+ */
+export function isCI(): boolean {
+  return ciInfoIsCI;
+}

package/src/utils/plan-resolution.ts

@@ -0,0 +1,257 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { ControlFamilyInstance } from '@prisma-next/framework-components/control';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import type { MigrationGraph } from '@prisma-next/migration-tools/graph';
+import {
+  assertHashIsGraphNode,
+  findLatestMigration,
+  isGraphNode,
+} from '@prisma-next/migration-tools/migration-graph';
+import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
+import type { Refs } from '@prisma-next/migration-tools/refs';
+import { readRefSnapshot, readRefs } from '@prisma-next/migration-tools/refs';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import {
+  CliStructuredError,
+  errorContractValidationFailed,
+  errorPlanForgotTheFlag,
+  errorSnapshotMissing,
+  errorUnexpected,
+  mapMigrationToolsError,
+  mapRefResolutionError,
+} from './cli-errors';
+
+const FULL_HASH_PATTERN = /^sha256:([0-9a-f]{64}|empty)$/;
+
+export function looksLikeFullHash(input: string): boolean {
+  return FULL_HASH_PATTERN.test(input);
+}
+
+export type FromResolution =
+  | { kind: 'greenfield'; fromHash: null; fromContract: null }
+  | { kind: 'graph-node'; fromHash: string; fromContract: Contract; sourceDir: string }
+  | {
+      kind: 'snapshot';
+      fromHash: string;
+      fromContract: Contract;
+      contractDts: string;
+      contractJson: unknown;
+    }
+  | {
+      kind: 'auto-baseline';
+      fromHash: string;
+      fromContract: Contract;
+      contractDts: string;
+      contractJson: unknown;
+    };
+
+export interface ResolveFromForPlanInput {
+  readonly optionsFrom?: string | undefined;
+  readonly refsDir: string;
+  readonly bundles: readonly OnDiskMigrationPackage[];
+  readonly graph: MigrationGraph;
+  readonly familyInstance: ControlFamilyInstance<string, unknown>;
+  readonly readBundleEndContract: (migrationDir: string) => Promise<Contract>;
+}
+
+function graphIsEmpty(bundles: readonly OnDiskMigrationPackage[]): boolean {
+  return bundles.length === 0;
+}
+
+function getReachableRefs(
+  refs: Refs,
+  graph: MigrationGraph,
+): ReadonlyArray<{ name: string; hash: string }> {
+  return Object.entries(refs)
+    .flatMap(([name, entry]) =>
+      entry && isGraphNode(entry.hash, graph) ? [{ name, hash: entry.hash }] : [],
+    )
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function assertFromIsGraphNode(
+  fromHash: string,
+  graph: MigrationGraph,
+  refs: Refs,
+  graphTipHash: string | null,
+): void {
+  try {
+    assertHashIsGraphNode(fromHash, graph);
+  } catch (error) {
+    if (MigrationToolsError.is(error) && error.code === 'MIGRATION.HASH_NOT_IN_GRAPH') {
+      throw errorPlanForgotTheFlag(fromHash, getReachableRefs(refs, graph), graphTipHash);
+    }
+    throw error;
+  }
+}
+
+async function deserializeSnapshotContract(
+  familyInstance: ControlFamilyInstance<string, unknown>,
+  contract: unknown,
+): Promise<Result<Contract, CliStructuredError>> {
+  try {
+    return ok(familyInstance.deserializeContract(contract));
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
+    return notOk(
+      errorContractValidationFailed(
+        `Ref snapshot contract failed to deserialize: ${error instanceof Error ? error.message : String(error)}`,
+        { where: { path: 'ref-snapshot' } },
+      ),
+    );
+  }
+}
+
+async function resolveGraphNodeFromBundle(
+  fromHash: string,
+  bundles: readonly OnDiskMigrationPackage[],
+  readBundleEndContract: (migrationDir: string) => Promise<Contract>,
+  explicitFromLabel?: string,
+): Promise<Result<Extract<FromResolution, { kind: 'graph-node' }>, CliStructuredError>> {
+  const matchingBundle = bundles.find((pkg) => pkg.metadata.to === fromHash);
+  if (!matchingBundle) {
+    return notOk(
+      errorUnexpected(
+        explicitFromLabel
+          ? `No migration bundle found for --from "${explicitFromLabel}" (resolved hash: ${fromHash})`
+          : `No migration bundle found for graph node ${fromHash}`,
+        {
+          why: `The hash ${fromHash} is a graph node but no on-disk migration package has an end-contract hash matching it.`,
+          fix: 'Provide a ref or hash that corresponds to an existing migration package, or run `migration list` to see available migrations.',
+        },
+      ),
+    );
+  }
+  try {
+    const fromContract = await readBundleEndContract(matchingBundle.dirPath);
+    return ok({
+      kind: 'graph-node',
+      fromHash,
+      fromContract,
+      sourceDir: matchingBundle.dirPath,
+    });
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
+    throw error;
+  }
+}
+
+async function resolveFromRefName(
+  refName: string,
+  fromHash: string,
+  input: ResolveFromForPlanInput,
+  refs: Refs,
+): Promise<Result<FromResolution, CliStructuredError>> {
+  const { refsDir, bundles, graph, familyInstance, readBundleEndContract } = input;
+  const empty = graphIsEmpty(bundles);
+  const graphTip = findLatestMigration(graph)?.to ?? null;
+
+  let snapshot: Awaited<ReturnType<typeof readRefSnapshot>>;
+  try {
+    snapshot = await readRefSnapshot(refsDir, refName);
+  } catch (error) {
+    if (MigrationToolsError.is(error)) {
+      return notOk(mapMigrationToolsError(error));
+    }
+    throw error;
+  }
+
+  if (snapshot) {
+    const contractResult = await deserializeSnapshotContract(familyInstance, snapshot.contract);
+    if (!contractResult.ok) {
+      return contractResult;
+    }
+    const fromContract = contractResult.value;
+    const { contractDts, contract: contractJson } = snapshot;
+    if (empty) {
+      return ok({ kind: 'auto-baseline', fromHash, fromContract, contractDts, contractJson });
+    }
+    try {
+      assertFromIsGraphNode(fromHash, graph, refs, graphTip);
+    } catch (error) {
+      if (CliStructuredError.is(error)) {
+        return notOk(error);
+      }
+      throw error;
+    }
+    return ok({ kind: 'snapshot', fromHash, fromContract, contractDts, contractJson });
+  }
+
+  if (isGraphNode(fromHash, graph)) {
+    return resolveGraphNodeFromBundle(fromHash, bundles, readBundleEndContract);
+  }
+
+  return notOk(errorSnapshotMissing(refName));
+}
+
+async function resolveFromHashProvenance(
+  fromHash: string,
+  input: ResolveFromForPlanInput,
+  _refs: Refs,
+  explicitFromLabel?: string,
+): Promise<Result<FromResolution, CliStructuredError>> {
+  const { bundles, graph } = input;
+
+  if (isGraphNode(fromHash, graph)) {
+    return resolveGraphNodeFromBundle(
+      fromHash,
+      bundles,
+      input.readBundleEndContract,
+      explicitFromLabel,
+    );
+  }
+
+  throw new Error(
+    `resolveFromHashProvenance: non-graph-node hash ${fromHash} should be refused via looksLikeFullHash before this helper is called`,
+  );
+}
+
+export async function resolveFromForPlan(
+  input: ResolveFromForPlanInput,
+): Promise<Result<FromResolution, CliStructuredError>> {
+  const { optionsFrom, refsDir, graph } = input;
+
+  let refs: Refs;
+  try {
+    refs = await readRefs(refsDir);
+  } catch (error) {
+    if (MigrationToolsError.is(error)) {
+      return notOk(mapMigrationToolsError(error));
+    }
+    throw error;
+  }
+
+  if (optionsFrom === undefined) {
+    const dbRef = refs['db'];
+    if (!dbRef) {
+      return ok({ kind: 'greenfield', fromHash: null, fromContract: null });
+    }
+    return resolveFromRefName('db', dbRef.hash, input, refs);
+  }
+
+  const refResult = parseContractRef(optionsFrom, { graph, refs });
+  if (!refResult.ok) {
+    if (looksLikeFullHash(optionsFrom)) {
+      const empty = graphIsEmpty(input.bundles);
+      const graphTip = findLatestMigration(graph)?.to ?? null;
+      if (empty) {
+        return notOk(errorSnapshotMissing(optionsFrom, { viaRef: false }));
+      }
+      return notOk(errorPlanForgotTheFlag(optionsFrom, getReachableRefs(refs, graph), graphTip));
+    }
+    return notOk(mapRefResolutionError(refResult.failure));
+  }
+
+  const { hash: fromHash, provenance } = refResult.value;
+
+  if (provenance.kind === 'ref') {
+    return resolveFromRefName(provenance.refName, fromHash, input, refs);
+  }
+
+  return resolveFromHashProvenance(fromHash, input, refs, optionsFrom);
+}

package/src/utils/ref-advancement.ts

@@ -0,0 +1,68 @@
+import { readFile } from 'node:fs/promises';
+import type { ContractIR } from '@prisma-next/migration-tools/refs';
+import { writeRefPaired } from '@prisma-next/migration-tools/refs';
+import { ifDefined } from '@prisma-next/utils/defined';
+
+export interface RefAdvancementFields {
+  readonly advancedRef: { readonly name: string; readonly hash: string } | null;
+  readonly plannedAdvanceRef: { readonly name: string; readonly hash: string } | null;
+}
+
+export function computeRefAdvancementName(options: {
+  readonly advanceRef?: string;
+  readonly db?: string;
+}): string | null {
+  if (options.advanceRef !== undefined) {
+    return options.advanceRef;
+  }
+  if (options.db === undefined) {
+    return 'db';
+  }
+  return null;
+}
+
+export async function readContractIR(
+  contractJson: Record<string, unknown>,
+  contractJsonPath: string,
+): Promise<ContractIR> {
+  const contractDtsPath = contractJsonPath.replace(/\.json$/i, '.d.ts');
+  const contractDts = await readFile(contractDtsPath, 'utf-8');
+  return { contract: contractJson, contractDts };
+}
+
+export async function executeRefAdvancement(
+  refsDir: string,
+  name: string,
+  hash: string,
+  contractIR: ContractIR,
+): Promise<{ name: string; hash: string }> {
+  await writeRefPaired(refsDir, name, { hash, invariants: [] }, contractIR);
+  return { name, hash };
+}
+
+export async function buildRefAdvancementFields(options: {
+  readonly advanceRef?: string;
+  readonly db?: string;
+  readonly refsDir: string;
+  readonly contractIR: ContractIR;
+  readonly mode: 'plan' | 'apply';
+  readonly hash: string;
+}): Promise<RefAdvancementFields> {
+  const name = computeRefAdvancementName({
+    ...ifDefined('advanceRef', options.advanceRef),
+    ...ifDefined('db', options.db),
+  });
+  if (name === null) {
+    return { advancedRef: null, plannedAdvanceRef: null };
+  }
+  if (options.mode === 'plan') {
+    return { advancedRef: null, plannedAdvanceRef: { name, hash: options.hash } };
+  }
+  const advancedRef = await executeRefAdvancement(
+    options.refsDir,
+    name,
+    options.hash,
+    options.contractIR,
+  );
+  return { advancedRef, plannedAdvanceRef: null };
+}

package/src/utils/telemetry.ts

@@ -0,0 +1,141 @@
+import { fileURLToPath } from 'node:url';
+import {
+  type CommanderOptionShape,
+  type CommanderResultShape,
+  readUserConfig,
+  resolveGating,
+  runTelemetry,
+  type TelemetryRunOutcome,
+  type UserConfig,
+} from '@prisma-next/cli-telemetry';
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { Command } from 'commander';
+import { version as CLI_VERSION } from '../../package.json' with { type: 'json' };
+import { isCI } from './is-ci';
+
+type TelemetryGate =
+  | { readonly enabled: true; readonly userConfig: UserConfig }
+  | { readonly enabled: false; readonly outcome: TelemetryRunOutcome };
+
+/**
+ * Resolve the commander command path from a leaf `Command`, walking up
+ * the parent chain. Result is rooted at the program name and ends at
+ * the leaf — `['prisma-next', 'migration', 'new']` for
+ * `prisma-next migration new …`.
+ */
+function commandPathFor(actionCommand: Command): string[] {
+  const path: string[] = [];
+  let cursor: Command | null = actionCommand;
+  while (cursor !== null) {
+    path.unshift(cursor.name());
+    cursor = cursor.parent;
+  }
+  return path;
+}
+
+function commanderOptionSnapshots(actionCommand: Command): CommanderOptionShape[] {
+  return actionCommand.options.map((option) => {
+    const attributeName = option.attributeName();
+    return {
+      attributeName,
+      longName: option.long ?? null,
+      source: actionCommand.getOptionValueSource(attributeName) ?? null,
+    };
+  });
+}
+
+/**
+ * Project commander's leaf `Command` into the wire-shape snapshot the
+ * telemetry sanitiser consumes. Pure projection — no env, no I/O.
+ */
+export function commanderSnapshotForTelemetry(actionCommand: Command): CommanderResultShape {
+  return {
+    commandPath: commandPathFor(actionCommand),
+    positionalArgs: actionCommand.args,
+    options: commanderOptionSnapshots(actionCommand),
+  };
+}
+
+function resolveTelemetryGate(): TelemetryGate {
+  if (isCI()) {
+    return { enabled: false, outcome: { spawned: false, reason: 'ci' } };
+  }
+  const userConfig = readUserConfig();
+  const gating = resolveGating({ env: process.env, config: userConfig });
+  if (!gating.enabled) {
+    return { enabled: false, outcome: { spawned: false, reason: 'gated-off' } };
+  }
+  return { enabled: true, userConfig };
+}
+
+/**
+ * Path to the compiled sender script inside `@prisma-next/cli-telemetry`'s
+ * `dist/`. Resolved off this module's `import.meta.url` via the package
+ * specifier `@prisma-next/cli-telemetry/sender`, so the consumer pays
+ * no attention to internal package layout.
+ */
+function senderPath(): string {
+  return fileURLToPath(new URL(import.meta.resolve('@prisma-next/cli-telemetry/sender')));
+}
+
+function fireTelemetry(
+  actionCommand: Command,
+  userConfig: UserConfig,
+  overrides: { readonly databaseTarget?: string } = {},
+): TelemetryRunOutcome {
+  return runTelemetry({
+    command: commanderSnapshotForTelemetry(actionCommand),
+    version: CLI_VERSION,
+    projectRoot: process.cwd(),
+    senderPath: senderPath(),
+    isCI: isCI(),
+    env: process.env,
+    userConfig,
+    ...ifDefined('databaseTarget', overrides.databaseTarget),
+  });
+}
+
+/**
+ * preAction-stage entry point. Synchronous by construction: resolve
+ * env/CI/user-consent gates (cheap, all in-memory and a single tiny
+ * user-config read), then — only when enabled — `fork()` the detached
+ * sender script. The forked child loads `prisma-next.config.*` via
+ * c12 on its own (see `loadProjectConfig` in cli-telemetry); the
+ * parent does no project-config I/O on the command's hot path.
+ *
+ * Privacy invariant: gate resolution always happens before any project
+ * config touches disk. The child loading user TS code is acceptable
+ * only because it's gated behind the same resolved-enabled signal.
+ */
+export function fireTelemetryFromPreAction(actionCommand: Command): TelemetryRunOutcome {
+  const gate = resolveTelemetryGate();
+  if (!gate.enabled) {
+    return gate.outcome;
+  }
+  return fireTelemetry(actionCommand, gate.userConfig);
+}
+
+/**
+ * Manual one-shot telemetry path for the first `init` run where the user
+ * explicitly answers Yes to the consent prompt. The preAction hook for
+ * that same run has already resolved before consent existed, so it is
+ * default-off. After consent is persisted, `runInit` calls this helper
+ * exactly for that first affirmative answer; subsequent init runs skip
+ * it because the prompt is not shown again.
+ *
+ * The child's c12 load would return `databaseTarget: null` for this
+ * specific invocation because `prisma-next.config.*` is not yet on
+ * disk (init writes it later in the same run). To preserve the
+ * prompt-chosen target in the first-init telemetry event, this
+ * helper forwards the value as a parent-side IPC override on
+ * `ParentToSenderPayload.databaseTarget` — the child consults the
+ * override first and falls back to its c12 result when absent.
+ */
+export function fireTelemetryAfterInitConsent(
+  actionCommand: Command,
+  inputs: { readonly databaseTarget: string },
+): TelemetryRunOutcome {
+  return fireTelemetry(actionCommand, readUserConfig(), {
+    databaseTarget: inputs.databaseTarget,
+  });
+}