cli-error-handling

CLI Error Handling

Pattern: Structured Errors + Result Pattern + process.exit()

CRITICAL: CLI commands use structured errors (CliStructuredError), the Result pattern (performAction), and process.exit() for exit codes. Commands never throw (except unhandled failures, which fail fast).

The architecture:

1. Structured errors: call sites throw CliStructuredError instances with full context (why, fix, docsUrl, etc.) — so they can provide actionable messages and metadata.
2. Result pattern: commands wrap logic in performAction(), which catches only CliStructuredError — cleanly separating action logic from error handling.
3. Error handling: handleResult() processes Results, formats output (JSON vs human), and returns an exit code.
4. Exit: commands call process.exit(exitCode) directly — never throw — so they control exit codes.
5. Fail fast: non-structured errors (bugs, unexpected failures) propagate with stack traces and are caught by Commander.js's exitOverride.

import { performAction } from '../utils/result';
import { handleResult } from '../utils/result-handler';
import { errorContractConfigMissing } from '../utils/cli-errors';

export function createEmitCommand(): Command {
  return new Command('emit').action(async (options) => {
    const flags = parseGlobalFlags(options);
    const result = await performAction(async () => {
      const config = await loadConfig(options.config);
      if (!config.contract) {
        throw errorContractConfigMissing({ why: 'Config.contract is required for emit' });
      }
      return emitResult;
    });
    const exitCode = handleResult(result, flags, (emitResult) => {
      console.log(formatEmitOutput(emitResult, flags));
    });
    process.exit(exitCode);
  });
}

Structured Error Factories

Create structured errors with the factory functions from utils/cli-errors.ts — they give type-safe, consistently-structured errors with call-site context and no fragile string matching in the mapper.