@vibecheckai/cli 3.2.5 → 3.3.0

package/bin/runners/lib/exit-codes.js

@@ -0,0 +1,275 @@
+/**
+ * Vibecheck CLI Exit Codes - Standardized for World-Class UX
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * EXIT CODE REFERENCE
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Standard Unix conventions extended for CLI tooling:
+ * 
+ * 0    SUCCESS         Command completed successfully, no issues found
+ * 1    WARNINGS        Command completed with warnings (non-blocking issues)
+ * 2    BLOCKING        Command found blocking issues (critical/high severity)
+ * 3    USER_ERROR      Invalid arguments, missing required flags, bad input
+ * 4    NOT_FOUND       Command not found, file not found, resource missing
+ * 5    AUTH_REQUIRED   Authentication required but not provided
+ * 6    AUTH_FAILED     Authentication failed (invalid/expired credentials)
+ * 7    TIER_REQUIRED   Feature requires higher subscription tier
+ * 8    RATE_LIMITED    API rate limit exceeded
+ * 9    NETWORK_ERROR   Network connectivity issue
+ * 10   INTERNAL_ERROR  Unexpected internal error
+ * 
+ * CI-Friendly: Exit codes 0-2 are "soft" (scan results), 3+ are "hard" (errors)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+
+"use strict";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXIT CODE CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const EXIT = {
+  // Success states (0-2)
+  SUCCESS: 0,           // All good, no issues
+  WARNINGS: 1,          // Completed with warnings (medium/low severity)
+  BLOCKING: 2,          // Blocking issues found (critical/high severity)
+  
+  // User errors (3-4)
+  USER_ERROR: 3,        // Bad args, invalid input, usage error
+  NOT_FOUND: 4,         // Resource/command/file not found
+  
+  // Auth errors (5-7)
+  AUTH_REQUIRED: 5,     // Need to log in
+  AUTH_FAILED: 6,       // Bad credentials
+  TIER_REQUIRED: 7,     // Need higher plan
+  
+  // Transient errors (8-9)
+  RATE_LIMITED: 8,      // Try again later
+  NETWORK_ERROR: 9,     // Connectivity issue
+  
+  // Fatal errors (10+)
+  INTERNAL_ERROR: 10,   // Bug, unexpected error
+  
+  // Process signals (standard Unix)
+  SIGINT: 130,          // Ctrl+C
+  SIGTERM: 143,         // kill
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXIT CODE METADATA
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const EXIT_INFO = {
+  [EXIT.SUCCESS]: {
+    name: "SUCCESS",
+    description: "Command completed successfully",
+    ciStatus: "success",
+    recoverable: true,
+  },
+  [EXIT.WARNINGS]: {
+    name: "WARNINGS",
+    description: "Completed with warnings (non-blocking issues)",
+    ciStatus: "warning",
+    recoverable: true,
+  },
+  [EXIT.BLOCKING]: {
+    name: "BLOCKING",
+    description: "Blocking issues found (critical/high severity)",
+    ciStatus: "failure",
+    recoverable: true,
+  },
+  [EXIT.USER_ERROR]: {
+    name: "USER_ERROR",
+    description: "Invalid arguments or usage",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Check command usage with --help",
+  },
+  [EXIT.NOT_FOUND]: {
+    name: "NOT_FOUND",
+    description: "Resource not found",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Verify the path or resource exists",
+  },
+  [EXIT.AUTH_REQUIRED]: {
+    name: "AUTH_REQUIRED",
+    description: "Authentication required",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Run 'vibecheck login' to authenticate",
+  },
+  [EXIT.AUTH_FAILED]: {
+    name: "AUTH_FAILED",
+    description: "Authentication failed",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Check your API key or run 'vibecheck login' again",
+  },
+  [EXIT.TIER_REQUIRED]: {
+    name: "TIER_REQUIRED",
+    description: "Higher subscription tier required",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Upgrade at https://vibecheckai.dev/pricing",
+  },
+  [EXIT.RATE_LIMITED]: {
+    name: "RATE_LIMITED",
+    description: "Rate limit exceeded",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Wait a moment and try again",
+  },
+  [EXIT.NETWORK_ERROR]: {
+    name: "NETWORK_ERROR",
+    description: "Network connectivity issue",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Check your internet connection or try --offline mode",
+  },
+  [EXIT.INTERNAL_ERROR]: {
+    name: "INTERNAL_ERROR",
+    description: "Unexpected internal error",
+    ciStatus: "failure",
+    recoverable: false,
+    hint: "Please report this issue at https://github.com/vibecheckai/vibecheck/issues",
+  },
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Convert verdict string to exit code
+ * @param {string} verdict - SHIP, WARN, BLOCK, PASS, FAIL
+ * @returns {number} exit code
+ */
+function verdictToExitCode(verdict) {
+  const v = String(verdict).toUpperCase();
+  if (v === "SHIP" || v === "PASS" || v === "SUCCESS" || v === "OK") {
+    return EXIT.SUCCESS;
+  }
+  if (v === "WARN" || v === "WARNING" || v === "WARNINGS") {
+    return EXIT.WARNINGS;
+  }
+  if (v === "BLOCK" || v === "FAIL" || v === "FAILURE" || v === "ERROR") {
+    return EXIT.BLOCKING;
+  }
+  return EXIT.WARNINGS; // Default to warnings for unknown
+}
+
+/**
+ * Convert exit code to verdict string
+ * @param {number} exitCode 
+ * @returns {string} verdict
+ */
+function exitCodeToVerdict(exitCode) {
+  switch (exitCode) {
+    case EXIT.SUCCESS: return "SHIP";
+    case EXIT.WARNINGS: return "WARN";
+    case EXIT.BLOCKING: return "BLOCK";
+    default: return "BLOCK";
+  }
+}
+
+/**
+ * Get exit info for an exit code
+ * @param {number} exitCode 
+ * @returns {object} exit info
+ */
+function getExitInfo(exitCode) {
+  return EXIT_INFO[exitCode] || EXIT_INFO[EXIT.INTERNAL_ERROR];
+}
+
+/**
+ * Check if exit code represents success (including warnings)
+ * @param {number} exitCode 
+ * @returns {boolean}
+ */
+function isSuccess(exitCode) {
+  return exitCode === EXIT.SUCCESS;
+}
+
+/**
+ * Check if exit code represents a "soft" failure (scan results, not errors)
+ * @param {number} exitCode 
+ * @returns {boolean}
+ */
+function isSoftFailure(exitCode) {
+  return exitCode === EXIT.WARNINGS || exitCode === EXIT.BLOCKING;
+}
+
+/**
+ * Check if exit code represents a "hard" failure (errors)
+ * @param {number} exitCode 
+ * @returns {boolean}
+ */
+function isHardFailure(exitCode) {
+  return exitCode >= EXIT.USER_ERROR;
+}
+
+/**
+ * Check if the error is recoverable (user can fix and retry)
+ * @param {number} exitCode 
+ * @returns {boolean}
+ */
+function isRecoverable(exitCode) {
+  const info = EXIT_INFO[exitCode];
+  return info ? info.recoverable : false;
+}
+
+/**
+ * Get hint message for exit code
+ * @param {number} exitCode 
+ * @returns {string|null}
+ */
+function getHint(exitCode) {
+  const info = EXIT_INFO[exitCode];
+  return info?.hint || null;
+}
+
+/**
+ * Get CI status for exit code
+ * @param {number} exitCode 
+ * @returns {string} "success" | "warning" | "failure"
+ */
+function getCIStatus(exitCode) {
+  const info = EXIT_INFO[exitCode];
+  return info?.ciStatus || "failure";
+}
+
+/**
+ * Create an error object with proper exit code
+ * @param {string} message 
+ * @param {number} exitCode 
+ * @param {object} details 
+ * @returns {Error}
+ */
+function createExitError(message, exitCode, details = {}) {
+  const error = new Error(message);
+  error.exitCode = exitCode;
+  error.exitInfo = getExitInfo(exitCode);
+  Object.assign(error, details);
+  return error;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  EXIT,
+  EXIT_INFO,
+  verdictToExitCode,
+  exitCodeToVerdict,
+  getExitInfo,
+  isSuccess,
+  isSoftFailure,
+  isHardFailure,
+  isRecoverable,
+  getHint,
+  getCIStatus,
+  createExitError,
+};