@prisma-next/cli 0.4.2 → 0.4.3

package/src/cli.ts

@@ -50,8 +50,18 @@ program.configureOutput({
   writeErr: () => {
     // Suppress all default error output - we handle errors in exitOverride
   },
-  writeOut: () => {
-    // Suppress all default output - our custom formatters handle everything
+  writeOut: (str) => {
+    // Commander routes explicitly-requested `--help` (success-path help)
+    // through writeOut; per the Style Guide § Output Conventions rule 8,
+    // user-requested help is data and goes to stdout. Error-path help
+    // (e.g. usage shown after an unknown command) goes through writeErr,
+    // which stays suppressed because we render that ourselves with the
+    // matching error envelope.
+    //
+    // Explicit `--version` is short-circuited before `program.parse()`
+    // (see the argv pre-scan at the bottom of this file), so it does not
+    // reach this writer.
+    process.stdout.write(str);
   },
 });
 
@@ -261,14 +271,25 @@ const helpCommand = new Command('help')
   .action(() => {
     const flags = parseGlobalFlags({});
     const helpText = formatRootHelp({ program, flags });
-    // Help is decoration → stderr
-    process.stderr.write(`${helpText}\n`);
+    // The `help` command was invoked explicitly: help is the data the
+    // caller asked for. Per Style Guide § Output Conventions rule 8,
+    // explicit help goes to stdout with exit code 0.
+    process.stdout.write(`${helpText}\n`);
     process.exit(0);
   });
 
 program.addCommand(helpCommand);
 
-// Set help as the default action when no command is provided
+// Set help as the default action when no command is provided. The user
+// did not invoke `--help`; we are voluntarily showing usage to help them
+// recover from an underspecified invocation, so the help text is
+// decoration around an implicit "what did you want me to do?" and goes
+// to stderr (Style Guide § Output Conventions rule 8).
+//
+// FOLLOW-UP: the exit code here is 0 today, but a no-arg invocation is
+// arguably a usage error (PRECONDITION → exit 2) for consistency with
+// the unknown-command path. Out of scope for the explicit-help routing
+// work; revisit when tightening exit-code semantics across the CLI.
 program.action(() => {
   const flags = parseGlobalFlags({});
   const helpText = formatRootHelp({ program, flags });
@@ -304,7 +325,12 @@ if (args.length > 0) {
       process.stderr.write(`${helpText}\n`);
       process.exit(2);
     } else if (command.commands.length > 0 && args.length === 1) {
-      // Parent command called with no subcommand - show help and exit with 0
+      // Parent command called with no subcommand. Same shape as the
+      // no-args case above: the user did not request help, we are
+      // voluntarily rendering it as decoration around an underspecified
+      // invocation, so it goes to stderr per Style Guide § Output
+      // Conventions rule 8. Exit code 0 today; the FOLLOW-UP note on
+      // `program.action` applies here too (arguably should be 2).
       const flags = parseGlobalFlags({});
       const helpText = formatCommandHelp({ command, flags });
       process.stderr.write(`${helpText}\n`);

package/src/commands/contract-emit.ts

@@ -1,18 +1,13 @@
-import { mkdirSync, writeFileSync } from 'node:fs';
 import { getEmittedArtifactPaths } from '@prisma-next/emitter';
 import { errorContractConfigMissing } from '@prisma-next/errors/control';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { dirname, relative, resolve } from 'pathe';
 import { loadConfig } from '../config-loader';
-import { createControlClient } from '../control-api/client';
-import type { EmitFailure } from '../control-api/types';
-import {
-  CliStructuredError,
-  errorContractValidationFailed,
-  errorRuntime,
-  errorUnexpected,
-} from '../utils/cli-errors';
+import { executeContractEmit } from '../control-api/operations/contract-emit';
+import type { ContractEmitResult } from '../control-api/types';
+import { CliStructuredError, errorUnexpected } from '../utils/cli-errors';
 import {
   addGlobalOptions,
   setCommandDescriptions,
@@ -34,74 +29,29 @@ interface ContractEmitOptions extends CommonCommandOptions {
   readonly config?: string;
 }
 
-function mapDiagnosticsToIssues(
-  failure: EmitFailure,
-): ReadonlyArray<{ kind: string; message: string }> {
-  const diagnostics = failure.diagnostics?.diagnostics ?? [];
-  return diagnostics.map((diagnostic) => {
-    const location =
-      diagnostic.sourceId && diagnostic.span
-        ? ` (${diagnostic.sourceId}:${diagnostic.span.start.line}:${diagnostic.span.start.column})`
-        : diagnostic.sourceId
-          ? ` (${diagnostic.sourceId})`
-          : '';
-    return {
-      kind: diagnostic.code,
-      message: `${diagnostic.message}${location}`,
-    };
-  });
+interface HeaderPaths {
+  readonly displayConfigPath: string;
+  readonly outputJsonPath: string;
+  readonly outputDtsPath: string;
 }
 
 /**
- * Maps an EmitFailure to a CliStructuredError for consistent error handling.
+ * Pre-load the config just to compute display paths for the styled header. The
+ * actual emit work goes through `executeContractEmit`, which loads the config
+ * itself; the redundant load here is bounded and lets the header render before
+ * the emit spans start.
  */
-function mapEmitFailure(
-  failure: EmitFailure,
-  context?: { readonly configPath?: string },
-): CliStructuredError {
-  if (failure.code === 'CONTRACT_SOURCE_INVALID') {
-    const issues = mapDiagnosticsToIssues(failure);
-    return errorRuntime(failure.summary, {
-      why: failure.why ?? 'Contract source provider failed',
-      fix: 'Check your contract source provider in prisma-next.config.ts and ensure it returns Result<Contract, Diagnostics>',
-      ...(issues.length > 0 ? { meta: { issues } } : {}),
-    });
-  }
-
-  if (failure.code === 'CONTRACT_VALIDATION_FAILED') {
-    return errorContractValidationFailed(
-      failure.why ?? 'Contract validation failed while emitting',
-      context?.configPath ? { where: { path: context.configPath } } : undefined,
-    );
-  }
-
-  if (failure.code === 'EMIT_FAILED') {
-    return errorRuntime(failure.summary, {
-      why: failure.why ?? 'Failed to emit contract',
-      fix: 'Check your contract configuration and ensure the source is valid',
-    });
-  }
-
-  // Exhaustive check - TypeScript will error if a new code is added but not handled
-  const exhaustive: never = failure.code;
-  throw new Error(`Unhandled EmitFailure code: ${exhaustive}`);
-}
+async function resolveHeaderPaths(
+  configOption: string | undefined,
+): Promise<Result<HeaderPaths, CliStructuredError>> {
+  const displayConfigPath = configOption
+    ? relative(process.cwd(), resolve(configOption))
+    : 'prisma-next.config.ts';
 
-/**
- * Executes the contract emit command and returns a structured Result.
- */
-async function executeContractEmitCommand(
-  options: ContractEmitOptions,
-  flags: GlobalFlags,
-  ui: TerminalUI,
-  startTime: number,
-): Promise<Result<EmitContractResult, CliStructuredError>> {
-  // Load config
   let config: Awaited<ReturnType<typeof loadConfig>>;
   try {
-    config = await loadConfig(options.config);
+    config = await loadConfig(configOption);
   } catch (error) {
-    // Convert thrown CliStructuredError to Result
     if (error instanceof CliStructuredError) {
       return notOk(error);
     }
@@ -112,33 +62,19 @@ async function executeContractEmitCommand(
     );
   }
 
-  const configPath = options.config
-    ? relative(process.cwd(), resolve(options.config))
-    : 'prisma-next.config.ts';
-
-  // Resolve contract from config
-  if (!config.contract) {
+  if (!config.contract?.output) {
     return notOk(
       errorContractConfigMissing({
-        why: 'Config.contract is required for emit. Define it in your config: contract: { source: ..., output: ... }',
+        why: 'Config.contract.output is required for emit. Define it in your config: contract: { source: ..., output: ... }',
       }),
     );
   }
 
-  // Contract config is already normalized by defineConfig() with defaults applied
-  const contractConfig = config.contract;
-
-  // Resolve artifact paths from config (already normalized by defineConfig() with defaults)
-  if (!contractConfig.output) {
-    return notOk(
-      errorContractConfigMissing({
-        why: 'Contract config must have output path. This should not happen if defineConfig() was used.',
-      }),
-    );
-  }
-  let outputPaths: ReturnType<typeof getEmittedArtifactPaths>;
   try {
-    outputPaths = getEmittedArtifactPaths(contractConfig.output);
+    const { jsonPath: outputJsonPath, dtsPath: outputDtsPath } = getEmittedArtifactPaths(
+      config.contract.output,
+    );
+    return ok({ displayConfigPath, outputJsonPath, outputDtsPath });
   } catch (error) {
     return notOk(
       errorContractConfigMissing({
@@ -146,96 +82,65 @@ async function executeContractEmitCommand(
       }),
     );
   }
-  const { jsonPath: outputJsonPath, dtsPath: outputDtsPath } = outputPaths;
+}
 
-  // Output header to stderr (decoration)
-  if (!flags.json && !flags.quiet) {
-    const contractPath = relative(process.cwd(), outputJsonPath);
-    const typesPath = relative(process.cwd(), outputDtsPath);
-    const header = formatStyledHeader({
-      command: 'contract emit',
-      description: 'Emit your contract artifacts',
-      url: 'https://pris.ly/contract-emit',
-      details: [
-        { label: 'config', value: configPath },
-        { label: 'contract', value: contractPath },
-        { label: 'types', value: typesPath },
-      ],
-      flags,
-    });
-    ui.stderr(header);
+async function executeContractEmitCommand(
+  options: ContractEmitOptions,
+  flags: GlobalFlags,
+  ui: TerminalUI,
+  startTime: number,
+): Promise<Result<EmitContractResult, CliStructuredError>> {
+  const headerPathsResult = await resolveHeaderPaths(options.config);
+  if (!headerPathsResult.ok) {
+    return headerPathsResult;
   }
+  const { displayConfigPath, outputJsonPath, outputDtsPath } = headerPathsResult.value;
 
-  // Create control client (no driver needed for emit)
-  const client = createControlClient({
-    family: config.family,
-    target: config.target,
-    adapter: config.adapter,
-    extensionPacks: config.extensionPacks ?? [],
-  });
+  if (!flags.json && !flags.quiet) {
+    ui.stderr(
+      formatStyledHeader({
+        command: 'contract emit',
+        description: 'Emit your contract artifacts',
+        url: 'https://pris.ly/contract-emit',
+        details: [
+          { label: 'config', value: displayConfigPath },
+          { label: 'contract', value: relative(process.cwd(), outputJsonPath) },
+          { label: 'types', value: relative(process.cwd(), outputDtsPath) },
+        ],
+        flags,
+      }),
+    );
+  }
 
-  // Create progress adapter
   const onProgress = createProgressAdapter({ ui, flags });
+  const configPath = options.config ? resolve(options.config) : 'prisma-next.config.ts';
 
+  let result: ContractEmitResult;
   try {
-    // Call emit with progress callback
-    const result = await client.emit({
-      contractConfig: {
-        source: contractConfig.source,
-        output: outputJsonPath,
-      },
-      onProgress,
-    });
-
-    // Handle failures by mapping to CLI structured error
-    if (!result.ok) {
-      return notOk(mapEmitFailure(result.failure, { configPath }));
-    }
-
-    // Create directories if needed
-    mkdirSync(dirname(outputJsonPath), { recursive: true });
-    mkdirSync(dirname(outputDtsPath), { recursive: true });
-
-    // Write the results to files
-    writeFileSync(outputJsonPath, result.value.contractJson, 'utf-8');
-    writeFileSync(outputDtsPath, result.value.contractDts, 'utf-8');
-
-    // Validate that contract.d.ts type imports are resolvable
-    const { validateContractDeps } = await import('../utils/validate-contract-deps');
-    const depsValidation = validateContractDeps(result.value.contractDts, dirname(outputDtsPath));
-    if (depsValidation.warning) {
-      ui.warn(depsValidation.warning);
-    }
-
-    // Convert success result to CLI output format
-    const emitResult: EmitContractResult = {
-      storageHash: result.value.storageHash,
-      ...(result.value.executionHash ? { executionHash: result.value.executionHash } : {}),
-      profileHash: result.value.profileHash,
-      outDir: dirname(outputJsonPath),
-      files: {
-        json: outputJsonPath,
-        dts: outputDtsPath,
-      },
-      timings: { total: Date.now() - startTime },
-    };
-
-    return ok(emitResult);
+    result = await executeContractEmit({ configPath, onProgress });
   } catch (error) {
-    // Use static type guard to work across module boundaries
     if (CliStructuredError.is(error)) {
       return notOk(error);
     }
-
-    // Wrap unexpected errors
     return notOk(
       errorUnexpected('Unexpected error during contract emit', {
         why: error instanceof Error ? error.message : String(error),
       }),
     );
-  } finally {
-    await client.close();
   }
+
+  if (result.validationWarning) {
+    ui.warn(result.validationWarning);
+  }
+
+  return ok({
+    storageHash: result.storageHash,
+    ...ifDefined('executionHash', result.executionHash),
+    profileHash: result.profileHash,
+    outDir: dirname(result.files.json),
+    files: result.files,
+    timings: { total: Date.now() - startTime },
+  });
 }
 
 export function createContractEmitCommand(): Command {
@@ -260,7 +165,6 @@ export function createContractEmitCommand(): Command {
 
       const result = await executeContractEmitCommand(options, flags, ui, startTime);
 
-      // Handle result - formats output and returns exit code
       const exitCode = handleResult(result, flags, ui, (emitResult) => {
         if (flags.json) {
           ui.output(formatEmitJson(emitResult));

package/src/commands/contract-infer.ts

@@ -1,12 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { errorRuntime } from '@prisma-next/errors/execution';
-import { printPsl, validatePrintableSqlSchemaIR } from '@prisma-next/psl-printer';
-import {
-  createPostgresDefaultMapping,
-  createPostgresTypeMap,
-  extractEnumInfo,
-  parseRawDefault,
-} from '@prisma-next/psl-printer/postgres';
+import { printPsl } from '@prisma-next/psl-printer';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { dirname, relative } from 'pathe';
@@ -59,26 +53,19 @@ async function executeContractInferCommand(
     return inspectResult;
   }
 
-  const { config, target, meta } = inspectResult.value;
+  const { config, target, meta, pslContractAst } = inspectResult.value;
 
-  if (target.familyId !== 'sql') {
+  if (!pslContractAst) {
     return notOk(
-      errorRuntime(`contract infer is not supported for family "${target.familyId}"`, {
-        why: 'contract infer currently supports SQL targets only',
-        fix: 'Use an SQL target (e.g. Postgres) with this command',
+      errorRuntime('contract infer is not supported for this family', {
+        why: 'The configured family does not implement the PslContractInferCapable capability, so an inferred PSL contract cannot be produced from the live database schema.',
+        fix: 'Use a family that supports contract inference (e.g. SQL/Postgres).',
       }),
     );
   }
 
-  const schema = validatePrintableSqlSchemaIR(inspectResult.value.schema);
   const outputPath = resolveContractInferOutputPath(options, config.contract?.output);
-  const enumInfo = extractEnumInfo(schema.annotations);
-  const pslContent = printPsl(schema, {
-    defaultMapping: createPostgresDefaultMapping(),
-    typeMap: createPostgresTypeMap(enumInfo.typeNames),
-    enumInfo,
-    parseRawDefault,
-  });
+  const pslContent = printPsl(pslContractAst);
 
   if (existsSync(outputPath) && !flags.json && !flags.quiet) {
     ui.stderr(`\u26A0 Overwriting existing file: ${relative(process.cwd(), outputPath)}`);

package/src/commands/db-init.ts

@@ -142,6 +142,7 @@ async function executeDbInitCommand(
           label: op.label,
           operationClass: op.operationClass,
         })),
+        ...ifDefined('preview', result.value.plan.preview),
       },
       ...(result.value.execution
         ? {

package/src/commands/db-update.ts

@@ -112,7 +112,7 @@ async function executeDbUpdateCommand(
           label: op.label,
           operationClass: op.operationClass,
         })),
-        ...ifDefined('sql', result.value.plan.sql),
+        ...ifDefined('preview', result.value.plan.preview),
       },
       ...ifDefined(
         'execution',

package/src/commands/inspect-live-schema.ts

@@ -1,5 +1,5 @@
 import type { CoreSchemaView } from '@prisma-next/framework-components/control';
-import { validatePrintableSqlSchemaIR } from '@prisma-next/psl-printer';
+import type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { relative, resolve } from 'pathe';
 import { loadConfig } from '../config-loader';
@@ -33,6 +33,12 @@ export interface InspectLiveSchemaResult {
   readonly config: LoadedCliConfig;
   readonly schema: unknown;
   readonly schemaView: CoreSchemaView | undefined;
+  /**
+   * PSL AST inferred from the introspected schema, when the configured family
+   * implements `PslContractInferCapable`. `undefined` for families that do not
+   * support inference (e.g. Mongo today).
+   */
+  readonly pslContractAst: PslDocumentAst | undefined;
   readonly target: {
     readonly familyId: string;
     readonly id: string;
@@ -122,14 +128,12 @@ export async function inspectLiveSchema(
   const onProgress = createProgressAdapter({ ui, flags });
 
   try {
-    const schemaIR = await client.introspect({
+    const schema = await client.introspect({
       connection: dbConnection,
       onProgress,
     });
-    // TODO(TML-2251): Remove SQL-specific branching — SQL should use the same family-agnostic path as Mongo.
-    const schema =
-      config.family.familyId === 'sql' ? validatePrintableSqlSchemaIR(schemaIR) : schemaIR;
     const schemaView = client.toSchemaView(schema);
+    const pslContractAst = client.inferPslContract(schema);
 
     const dbUrl = typeof dbConnection === 'string' ? maskConnectionUrl(dbConnection) : undefined;
 
@@ -137,6 +141,7 @@ export async function inspectLiveSchema(
       config,
       schema,
       schemaView,
+      pslContractAst,
       target: {
         familyId: config.family.familyId,
         id: config.target.targetId,