@prisma-next/cli 0.10.0 → 0.11.0

package/src/commands/migration-list.ts

@@ -20,9 +20,9 @@ import {
 } from '../utils/command-helpers';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationListOptions extends CommonCommandOptions {
   readonly config?: string;
@@ -130,8 +130,8 @@ export function createMigrationListCommand(): Command {
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: MigrationListOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const result = await executeMigrationListCommand(options, flags, ui);
       const exitCode = handleResult(result, flags, ui, (listResult) => {
         if (flags.json) {

package/src/commands/migration-log.ts

@@ -8,7 +8,7 @@ import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import {
-  type CliStructuredError,
+  CliStructuredError,
   errorDatabaseConnectionRequired,
   errorDriverRequired,
   errorUnexpected,
@@ -26,9 +26,9 @@ import {
 } from '../utils/command-helpers';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationLogOptions extends CommonCommandOptions {
   readonly db?: string;
@@ -159,6 +159,7 @@ async function executeMigrationLogCommand(
       summary: `${entries.length} migration(s) applied`,
     });
   } catch (error) {
+    if (CliStructuredError.is(error)) return notOk(error);
     if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
     return notOk(
       errorUnexpected(error instanceof Error ? error.message : String(error), {
@@ -192,8 +193,8 @@ export function createMigrationLogCommand(): Command {
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: MigrationLogOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const result = await executeMigrationLogCommand(options, flags, ui);
       const exitCode = handleResult(result, flags, ui, (logResult) => {
         if (flags.json) {

package/src/commands/migration-new.ts

@@ -49,9 +49,9 @@ import {
 import { formatStyledHeader } from '../utils/formatters/styled';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { parseGlobalFlags } from '../utils/global-flags';
+import { parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI } from '../utils/terminal-ui';
 
 interface MigrationNewOptions extends CommonCommandOptions {
   readonly name?: string;
@@ -287,8 +287,8 @@ export function createMigrationNewCommand(): Command {
     .option('--from <hash>', 'Starting contract hash (default: latest migration target)')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: MigrationNewOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
 
       if (!flags.json && !flags.quiet) {
         const header = formatStyledHeader({

package/src/commands/migration-plan.ts

@@ -51,9 +51,9 @@ import { toExtensionInputs } from '../utils/extension-pack-inputs';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationPlanOptions extends CommonCommandOptions {
   readonly config?: string;
@@ -551,10 +551,10 @@ export function createMigrationPlanCommand(): Command {
       'Starting contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
     )
     .action(async (options: MigrationPlanOptions) => {
-      const flags = parseGlobalFlags(options);
+      const flags = parseGlobalFlagsOrExit(options);
       const startTime = Date.now();
 
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const ui = createTerminalUI(flags);
       const result = await executeMigrationPlanCommand(options, flags, ui, startTime);
 
       const exitCode = handleResult(result, flags, ui, (planResult) => {

package/src/commands/migration-show.ts

@@ -43,9 +43,9 @@ import { buildContractSpaceAggregate } from '../utils/contract-space-aggregate-l
 import { formatMigrationShowOutput } from '../utils/formatters/migrations';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationShowOptions extends CommonCommandOptions {
   readonly config?: string;
@@ -495,9 +495,9 @@ export function createMigrationShowCommand(): Command {
     )
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (target: string | undefined, options: MigrationShowOptions) => {
-      const flags = parseGlobalFlags(options);
+      const flags = parseGlobalFlagsOrExit(options);
 
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const ui = createTerminalUI(flags);
 
       const result = await executeMigrationShowCommand(target, options, flags, ui);
 

package/src/commands/migration-status.ts

@@ -30,7 +30,7 @@ import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import {
-  type CliStructuredError,
+  CliStructuredError,
   errorRuntime,
   errorUnexpected,
   mapMigrationToolsError,
@@ -65,10 +65,10 @@ import {
 } from '../utils/formatters/graph-render';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import type { StatusDiagnostic, StatusRef } from '../utils/migration-types';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationStatusOptions extends CommonCommandOptions {
   readonly db?: string;
@@ -540,6 +540,40 @@ async function loadContractRawSafely(config: {
   }
 }
 
+async function validateOnlineMarkerRead(
+  config: Awaited<ReturnType<typeof loadConfig>>,
+  dbConnection: unknown,
+): Promise<Result<void, CliStructuredError>> {
+  const driver = config.driver;
+  if (!driver) {
+    return ok(undefined);
+  }
+
+  const client = createControlClient({
+    family: config.family,
+    target: config.target,
+    adapter: config.adapter,
+    driver,
+    extensionPacks: config.extensionPacks ?? [],
+  });
+  try {
+    await client.connect(dbConnection);
+    await client.readMarker();
+    return ok(undefined);
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to read database marker: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  } finally {
+    await client.close();
+  }
+}
+
 async function executeMigrationStatusCommand(
   options: MigrationStatusOptions,
   flags: GlobalFlags,
@@ -666,6 +700,12 @@ async function executeMigrationStatusCommand(
   }
 
   if (bundles.length === 0) {
+    if (dbConnection && hasDriver) {
+      const markerProbe = await validateOnlineMarkerRead(config, dbConnection);
+      if (!markerProbe.ok) {
+        return markerProbe;
+      }
+    }
     if (contractHash !== EMPTY_CONTRACT_HASH) {
       diagnostics.push({
         code: 'CONTRACT.AHEAD',
@@ -750,7 +790,10 @@ async function executeMigrationStatusCommand(
         // space has no marker", which is a different condition).
         allMarkers = null;
       }
-    } catch {
+    } catch (error) {
+      if (CliStructuredError.is(error)) {
+        return notOk(error);
+      }
       if (!flags.json && !flags.quiet) {
         ui.warn('Could not connect to database — showing offline status');
       }
@@ -1097,8 +1140,8 @@ export function createMigrationStatusCommand(): Command {
       'Origin contract reference; same grammar as --to. Supplying --from switches to offline path computation.',
     )
     .action(async (options: MigrationStatusOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
 
       const result = await executeMigrationStatusCommand(options, flags, ui);
 

package/src/commands/ref.ts

@@ -25,9 +25,9 @@ import {
   setCommandDescriptions,
 } from '../utils/command-helpers';
 import { formatCommandHelp } from '../utils/formatters/help';
-import { parseGlobalFlags } from '../utils/global-flags';
+import { parseGlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI } from '../utils/terminal-ui';
 
 interface RefSetResult {
   readonly ok: true;
@@ -145,8 +145,8 @@ function createRefSetCommand(): Command {
         hash: string,
         options: { config?: string; json?: string | boolean; quiet?: boolean },
       ) => {
-        const flags = parseGlobalFlags(options);
-        const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+        const flags = parseGlobalFlagsOrExit(options);
+        const ui = createTerminalUI(flags);
         const result = await executeRefSetCommand(name, hash, options);
         const exitCode = handleResult(result, flags, ui, (value) => {
           if (flags.json) {
@@ -172,8 +172,8 @@ function createRefDeleteCommand(): Command {
         name: string,
         options: { config?: string; json?: string | boolean; quiet?: boolean },
       ) => {
-        const flags = parseGlobalFlags(options);
-        const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+        const flags = parseGlobalFlagsOrExit(options);
+        const ui = createTerminalUI(flags);
         const result = await executeRefDeleteCommand(name, options);
         const exitCode = handleResult(result, flags, ui, (value) => {
           if (flags.json) {
@@ -194,8 +194,8 @@ function createRefListCommand(): Command {
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: { config?: string; json?: string | boolean; quiet?: boolean }) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const result = await executeRefListCommand(options);
       const exitCode = handleResult(result, flags, ui, (value) => {
         if (flags.json) {

package/src/control-api/operations/apply-aggregate.ts

@@ -178,6 +178,7 @@ export async function applyAggregate<TFamilyId extends string, TTargetId extends
       meta: {
         ...(runnerResult.failure.meta ?? {}),
         failingSpace: runnerResult.failure.failingSpace,
+        runnerErrorCode: runnerResult.failure.code,
       },
     });
   }

package/src/utils/cli-errors.ts

@@ -16,9 +16,11 @@ import {
   errorDriverRequired,
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,
+  errorInvalidOutputFormat,
   errorMigrationCliInvalidConfigArg,
   errorMigrationCliUnknownFlag,
   errorMigrationPlanningFailed,
+  errorOutputFormatMutex,
   errorQueryRunnerFactoryRequired,
   errorTargetMigrationNotSupported,
   errorUnexpected,
@@ -56,9 +58,11 @@ export {
   errorDriverRequired,
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,
+  errorInvalidOutputFormat,
   errorMigrationCliInvalidConfigArg,
   errorMigrationCliUnknownFlag,
   errorMigrationPlanningFailed,
+  errorOutputFormatMutex,
   errorQueryRunnerFactoryRequired,
   errorTargetMigrationNotSupported,
   errorUnexpected,

package/src/utils/command-helpers.ts

@@ -365,7 +365,7 @@ export function sanitizeErrorMessage(message: string, connectionUrl?: string): s
 
 /**
  * Registers the global CLI options shared by every command:
- * --json, -q/--quiet, -v/--verbose, --trace, --color, --no-color,
+ * --format, --json, -q/--quiet, -v/--verbose, --trace, --color, --no-color,
  * --interactive, --no-interactive, -y/--yes.
  *
  * Also sets up the styled help formatter.
@@ -378,7 +378,11 @@ export function addGlobalOptions(command: Command): Command {
         return formatCommandHelp({ command: cmd, flags });
       },
     })
-    .option('--json', 'Output as JSON')
+    .option(
+      '--format <pretty|json>',
+      'Output format (default: pretty, or json when stdout is not a TTY)',
+    )
+    .option('--json', 'Output as JSON (alias for --format json)')
     .option('-q, --quiet', 'Quiet mode: errors only')
     .option('-v, --verbose', 'Verbose output: debug info, timings')
     .option('--trace', 'Trace output: deep internals, stack traces')

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;
+}