feat(cli): enhance error handling with network diagnostics and timeout errors

Add comprehensive error handling improvements aligned with socket-sdk-js:

- Add TimeoutError class with elapsed time tracking and retry guidance
- Add network error diagnostics with specific guidance for:
  - Timeout errors (ETIMEDOUT, ESOCKETTIMEDOUT, ECONNRESET)
  - Connection failures (ECONNREFUSED)
  - DNS issues (ENOTFOUND, EAI_AGAIN)
  - SSL/TLS certificate errors
  - Network unreachable scenarios
- Add type guards: isNetworkError(), isTimeoutError()
- Add getNetworkErrorDiagnostics() helper with actionable recovery steps
- Centralize Socket.dev URLs as constants (status, dashboard, pricing, etc.)
- Enhance queryApiSafeText() and sendApiRequest() with network diagnostics
- Add comprehensive test coverage (61 tests, all passing)

Benefits:
- Users get specific, actionable guidance for network errors
- Faster troubleshooting with clear diagnostics
- Consistent messaging via URL constants
- Better alignment with socket-sdk-js and socket-lib

Author: jdalton

packages/cli/src/constants/socket.mts

@@ -8,6 +8,12 @@ export { NPM_REGISTRY_URL } from '@socketsecurity/lib/constants/agents'
 // Socket API URLs
 export const API_V0_URL = 'https://api.socket.dev/v0/'
 export const SOCKET_WEBSITE_URL = 'https://socket.dev'
+export const SOCKET_CONTACT_URL = 'https://socket.dev/contact'
+export const SOCKET_DASHBOARD_URL = 'https://socket.dev/dashboard'
+export const SOCKET_PRICING_URL = 'https://socket.dev/pricing'
+export const SOCKET_SETTINGS_API_TOKENS_URL =
+  'https://socket.dev/settings/api-tokens'
+export const SOCKET_STATUS_URL = 'https://status.socket.dev'
 
 // Socket Configuration Files
 export const SOCKET_JSON = 'socket.json'
@@ -25,3 +31,7 @@ export const TOKEN_PREFIX_LENGTH = TOKEN_PREFIX.length
 // Documentation
 export const V1_MIGRATION_GUIDE_URL =
   'https://docs.socket.dev/docs/v1-migration-guide'
+
+// GitHub
+export const SOCKET_CLI_ISSUES_URL =
+  'https://github.com/SocketDev/socket-cli/issues'

packages/cli/src/utils/error/errors.mts

@@ -27,6 +27,11 @@ import {
 import { debugNs } from '@socketsecurity/lib/debug'
 
 import ENV from '../../constants/env.mts'
+import {
+  SOCKET_DASHBOARD_URL,
+  SOCKET_PRICING_URL,
+  SOCKET_STATUS_URL,
+} from '../../constants/socket.mts'
 
 import type { RegistryInternals } from '../../constants/types.mts'
 
@@ -111,8 +116,8 @@ export class RateLimitError extends Error {
       retryAfter
         ? `Wait ${retryAfter} seconds before retrying`
         : 'Wait a few minutes before retrying',
-      'Check your API quota at https://socket.dev/dashboard',
-      'Consider upgrading your plan for higher limits',
+      `Check your API quota at ${SOCKET_DASHBOARD_URL}`,
+      `Consider upgrading your plan for higher limits at ${SOCKET_PRICING_URL}`,
     ]
   }
 }
@@ -190,6 +195,33 @@ export class ConfigError extends Error {
   }
 }
 
+/**
+ * Timeout error with retry guidance.
+ * Thrown when operations exceed time limits.
+ */
+export class TimeoutError extends Error {
+  public readonly timeoutMs?: number | undefined
+  public readonly elapsedMs?: number | undefined
+  public readonly recovery: string[]
+
+  constructor(
+    message: string,
+    timeoutMs?: number | undefined,
+    elapsedMs?: number | undefined,
+    recovery?: string[] | undefined,
+  ) {
+    super(message)
+    this.name = 'TimeoutError'
+    this.timeoutMs = timeoutMs
+    this.elapsedMs = elapsedMs
+    this.recovery = recovery || [
+      'Check your internet connection speed',
+      'Try again when network conditions improve',
+      'Contact support if timeouts persist',
+    ]
+  }
+}
+
 export async function captureException(
   exception: unknown,
   hint?: EventHintOrCaptureContext | undefined,
@@ -353,3 +385,133 @@ export async function buildErrorCause(
     ? `${message} (reason: ${reason})`
     : message
 }
+
+/**
+ * Type guard to check if an error is a network error.
+ */
+export function isNetworkError(error: unknown): error is NetworkError {
+  return error instanceof NetworkError
+}
+
+/**
+ * Type guard to check if an error is a timeout error.
+ */
+export function isTimeoutError(error: unknown): error is TimeoutError {
+  return error instanceof TimeoutError
+}
+
+/**
+ * Detect network-related error codes from Node.js errors.
+ */
+export function getNetworkErrorCode(error: unknown): string | undefined {
+  if (!isErrnoException(error)) {
+    return undefined
+  }
+  return error.code
+}
+
+/**
+ * Get network error diagnostics with actionable guidance.
+ * Provides specific recovery steps based on error type.
+ *
+ * @param error - The error to diagnose
+ * @param durationMs - Optional request duration in milliseconds
+ * @returns Diagnostic message with recovery suggestions
+ *
+ * @example
+ * const diagnostics = getNetworkErrorDiagnostics(error, 5000)
+ * // Returns: "Connection refused. The server may be down..."
+ */
+export function getNetworkErrorDiagnostics(
+  error: unknown,
+  durationMs?: number | undefined,
+): string {
+  const errorCode = getNetworkErrorCode(error)
+  const errorMessage = getErrorMessage(error) || String(error)
+
+  // Timeout errors.
+  if (
+    errorCode === 'ETIMEDOUT' ||
+    errorCode === 'ESOCKETTIMEDOUT' ||
+    errorCode === 'ECONNRESET' ||
+    (durationMs && durationMs > 30_000)
+  ) {
+    const timeInfo = durationMs ? ` after ${Math.round(durationMs / 1000)}s` : ''
+    return (
+      `Request timeout${timeInfo}. The server took too long to respond.\n` +
+      '💡 Try:\n' +
+      '  • Check your internet connection speed\n' +
+      '  • Retry the request - the server may be temporarily slow\n' +
+      `  • Check Socket status: ${SOCKET_STATUS_URL}\n` +
+      '  • Contact support if timeouts persist'
+    )
+  }
+
+  // Connection refused.
+  if (errorCode === 'ECONNREFUSED') {
+    return (
+      'Connection refused. The server actively rejected the connection.\n' +
+      '💡 Try:\n' +
+      '  • Check if you are using a proxy or VPN that may be blocking the connection\n' +
+      '  • Verify your firewall settings\n' +
+      `  • Check Socket status: ${SOCKET_STATUS_URL}\n` +
+      '  • Ensure SOCKET_CLI_API_BASE_URL is set correctly (if configured)'
+    )
+  }
+
+  // DNS resolution failures.
+  if (
+    errorCode === 'ENOTFOUND' ||
+    errorCode === 'EAI_AGAIN' ||
+    errorMessage.includes('getaddrinfo')
+  ) {
+    return (
+      'DNS resolution failed. Unable to resolve the server hostname.\n' +
+      '💡 Try:\n' +
+      '  • Check your internet connection\n' +
+      '  • Verify DNS settings (try 8.8.8.8 or 1.1.1.1)\n' +
+      '  • Check if a VPN or proxy is interfering\n' +
+      '  • Ensure SOCKET_CLI_API_BASE_URL is correct (if configured)\n' +
+      '  • Try again in a few moments'
+    )
+  }
+
+  // Certificate/SSL errors.
+  if (
+    errorCode === 'CERT_HAS_EXPIRED' ||
+    errorCode === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE' ||
+    errorCode === 'SELF_SIGNED_CERT_IN_CHAIN' ||
+    errorMessage.includes('certificate')
+  ) {
+    return (
+      'SSL/TLS certificate error. Unable to verify server identity.\n' +
+      '💡 Try:\n' +
+      '  • Check your system date and time are correct\n' +
+      '  • Update your system certificates\n' +
+      '  • Check if a proxy is intercepting HTTPS traffic\n' +
+      '  • Contact your IT department if behind corporate firewall'
+    )
+  }
+
+  // Network unreachable.
+  if (errorCode === 'ENETUNREACH' || errorCode === 'EHOSTUNREACH') {
+    return (
+      'Network unreachable. Cannot reach the destination network.\n' +
+      '💡 Try:\n' +
+      '  • Check your internet connection\n' +
+      '  • Verify network/WiFi is connected\n' +
+      '  • Check if VPN or firewall is blocking access\n' +
+      '  • Try a different network'
+    )
+  }
+
+  // Generic network error with basic guidance.
+  return (
+    `Network error: ${errorMessage}\n` +
+    '💡 Try:\n' +
+    '  • Check your internet connection\n' +
+    '  • Verify proxy settings if using a proxy\n' +
+    `  • Check Socket status: ${SOCKET_STATUS_URL}\n` +
+    '  • Try again in a few moments'
+  )
+}