Skip to content

The Open Standard for Generative UI

7.5 KB
Raw Blame
import type { CommandResult } from "./process-runner";

/** Thrown by command funnels so the index wrapper can attribute the failure stage + drain once. */
export type CliErrorClass =
  | "invalid_input"
  | "filesystem"
  | "authentication"
  | "dependency"
  | "peer_dependency"
  | "registry_auth"
  | "network"
  | "package_compatibility"
  | "workspace_config"
  | "install_script"
  | "process"
  | "user_cancelled"
  | "generation"
  | "unknown";

export type CliErrorMetadata = {
  duration_ms?: number;
  exit_code?: number;
  failure_signal?: NodeJS.Signals;
  http_status?: number;
  cancellation_exit_code?: number;
  auth_failure_stage?: string;
  attempts?: number;
};

export class CreateError extends Error {
  constructor(
    public stage: string,
    message: string,
    public errorClass: CliErrorClass = "unknown",
    public errorCode = "UNKNOWN",
    public errorMetadata: CliErrorMetadata = {},
  ) {
    super(message);
    this.name = "CreateError";
  }
}

export class CliCancelledError extends CreateError {
  constructor(
    stage: string,
    public exitCode = 0,
    metadata: CliErrorMetadata = {},
  ) {
    super(
      stage,
      "Operation cancelled.",
      "user_cancelled",
      exitCode === 0 ? "USER_CANCELLED" : exitCode === 143 ? "TERMINATED" : "INTERRUPTED",
      { ...metadata, cancellation_exit_code: exitCode },
    );
    this.name = "CliCancelledError";
  }
}

export type CliErrorProperties = CliErrorMetadata & {
  failure_stage: string;
  error_class: CliErrorClass;
  error_code: string;
};

const errnoTelemetry: Record<string, Pick<CliErrorProperties, "error_class" | "error_code">> = {
  EACCES: { error_class: "filesystem", error_code: "PERMISSION_DENIED" },
  EPERM: { error_class: "filesystem", error_code: "PERMISSION_DENIED" },
  ENOENT: { error_class: "filesystem", error_code: "NOT_FOUND" },
  ENOSPC: { error_class: "filesystem", error_code: "DISK_FULL" },
};

/** Return only bounded values; never forward an error message or stack. */
export function cliErrorProperties(
  error: unknown,
  fallback: CliErrorProperties = {
    failure_stage: "unknown",
    error_class: "unknown",
    error_code: "UNKNOWN",
  },
): CliErrorProperties {
  if (error instanceof CreateError) {
    return {
      failure_stage: error.stage,
      error_class: error.errorClass,
      error_code: error.errorCode,
      ...error.errorMetadata,
    };
  }

  const errno = error instanceof Error ? (error as NodeJS.ErrnoException).code : undefined;
  const classified = errno ? errnoTelemetry[errno] : undefined;
  return classified ? { ...fallback, ...classified } : fallback;
}

type ProcessFailureRule = {
  fingerprints: readonly string[];
  prefixes?: readonly string[];
  errorClass: CliErrorClass;
  errorCode: string;
};

const processFailureRules = [
  {
    fingerprints: ["ERR_PNPM_PEER_DEP_ISSUES", "YN0002", "YN0060", "ERESOLVE"],
    errorClass: "peer_dependency",
    errorCode: "PEER_DEPENDENCY",
  },
  {
    fingerprints: ["ERR_PNPM_FETCH_401", "E401", "ENEEDAUTH"],
    errorClass: "registry_auth",
    errorCode: "REGISTRY_401",
  },
  {
    fingerprints: ["ERR_PNPM_FETCH_403", "E403"],
    errorClass: "registry_auth",
    errorCode: "REGISTRY_403",
  },
  {
    fingerprints: ["ERR_PNPM_FETCH_404", "E404"],
    errorClass: "dependency",
    errorCode: "PACKAGE_NOT_FOUND",
  },
  {
    fingerprints: ["ENOTFOUND", "EAI_AGAIN"],
    errorClass: "network",
    errorCode: "DNS_FAILED",
  },
  {
    fingerprints: ["ETIMEDOUT", "ESOCKETTIMEDOUT", "ERR_SOCKET_TIMEOUT"],
    errorClass: "network",
    errorCode: "NETWORK_TIMEOUT",
  },
  {
    fingerprints: ["ECONNRESET", "ECONNREFUSED", "EHOSTUNREACH", "ENETUNREACH"],
    errorClass: "network",
    errorCode: "NETWORK_FAILED",
  },
  {
    fingerprints: [
      "ERR_PNPM_UNSUPPORTED_ENGINE",
      "ERR_PNPM_BAD_PM_VERSION",
      "EBADENGINE",
      "YN0009",
    ],
    errorClass: "package_compatibility",
    errorCode: "ENGINE_MISMATCH",
  },
  {
    fingerprints: ["ERR_PNPM_NO_MATCHING_VERSION", "ETARGET"],
    errorClass: "package_compatibility",
    errorCode: "NO_MATCHING_VERSION",
  },
  {
    fingerprints: ["ERR_PNPM_OUTDATED_LOCKFILE", "ERR_PNPM_LOCKFILE_BREAKING_CHANGE"],
    errorClass: "workspace_config",
    errorCode: "LOCKFILE_INCOMPATIBLE",
  },
  {
    fingerprints: ["ERR_PNPM_NO_MATCHING_VERSION_INSIDE_WORKSPACE"],
    prefixes: ["ERR_PNPM_WORKSPACE_"],
    errorClass: "workspace_config",
    errorCode: "WORKSPACE_CONFIG_INVALID",
  },
  {
    fingerprints: ["ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL", "ELIFECYCLE"],
    errorClass: "install_script",
    errorCode: "INSTALL_SCRIPT_FAILED",
  },
  {
    fingerprints: ["EACCES", "EPERM"],
    errorClass: "filesystem",
    errorCode: "PERMISSION_DENIED",
  },
  {
    fingerprints: ["ENOSPC", "EDQUOT"],
    errorClass: "filesystem",
    errorCode: "DISK_FULL",
  },
] satisfies readonly ProcessFailureRule[];

function classifyProcessDiagnostic(diagnostic: string): ProcessFailureRule | undefined {
  const tokens = diagnostic.toUpperCase().match(/\b[A-Z][A-Z0-9_]{2,}\b/g) ?? [];
  const tokenSet = new Set(tokens);
  return processFailureRules.find(
    ({ fingerprints, prefixes }) =>
      fingerprints.some((fingerprint) => tokenSet.has(fingerprint)) ||
      prefixes?.some((prefix) => tokens.some((token) => token.startsWith(prefix))),
  );
}

export function processErrorProperties(
  result: CommandResult,
  failureStage: string,
  fallback: Pick<CliErrorProperties, "error_class" | "error_code">,
): CliErrorProperties {
  const metadata: CliErrorMetadata = {
    duration_ms: result.durationMs,
    ...(typeof result.status === "number" ? { exit_code: result.status } : {}),
    ...(result.signal ? { failure_signal: result.signal } : {}),
  };
  const cancellationExitCode =
    result.signal === "SIGINT" || result.status === 130
      ? 130
      : result.signal === "SIGTERM" || result.status === 143
        ? 143
        : undefined;
  if (cancellationExitCode) {
    return {
      failure_stage: failureStage,
      error_class: "user_cancelled",
      error_code: cancellationExitCode === 130 ? "INTERRUPTED" : "TERMINATED",
      ...metadata,
      cancellation_exit_code: cancellationExitCode,
    };
  }

  const diagnostic = `${result.error?.message ?? ""}\n${result.diagnosticTail}`;
  const rule = classifyProcessDiagnostic(diagnostic);
  if (rule) {
    return {
      failure_stage: failureStage,
      error_class: rule.errorClass,
      error_code: rule.errorCode,
      ...metadata,
    };
  }

  const spawnCode = result.error ? (result.error as NodeJS.ErrnoException).code : undefined;
  if (spawnCode === "ENOENT") {
    return {
      failure_stage: failureStage,
      error_class: "process",
      error_code: "COMMAND_NOT_FOUND",
      ...metadata,
    };
  }

  return { failure_stage: failureStage, ...fallback, ...metadata };
}

const DEFAULT_PROCESS_FALLBACK: Pick<CliErrorProperties, "error_class" | "error_code"> = {
  error_class: "process",
  error_code: "NONZERO_EXIT",
};

/** Throw a typed CLI error (or cancellation) from a failed child process. */
export function throwCommandFailure(
  result: CommandResult,
  stage: string,
  message: string,
  fallback: Pick<CliErrorProperties, "error_class" | "error_code"> = DEFAULT_PROCESS_FALLBACK,
): never {
  const properties = processErrorProperties(result, stage, fallback);
  if (properties.error_class === "user_cancelled") {
    throw new CliCancelledError(stage, properties.cancellation_exit_code ?? 0, properties);
  }
  const { failure_stage, error_class, error_code, ...metadata } = properties;
  throw new CreateError(failure_stage, message, error_class, error_code, metadata);
}