claude-comms 1.0.0 → 1.0.2

package/src/utils/errors.js

@@ -0,0 +1,361 @@
+/**
+ * Custom error classes for standardized error handling
+ * Provides consistent error codes and messages across the NPX installer
+ */
+
+/**
+ * Base installer error with error codes and details
+ */
+class InstallerError extends Error {
+  constructor(message, code, details = null, cause = null) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.details = details;
+    this.cause = cause;
+    this.timestamp = new Date().toISOString();
+
+    // Maintain stack trace for V8
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * Convert error to JSON for logging/debugging
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      details: this.details,
+      timestamp: this.timestamp,
+      stack: this.stack
+    };
+  }
+
+  /**
+   * Get user-friendly error message
+   */
+  getUserMessage() {
+    return this.message;
+  }
+
+  /**
+   * Check if error is recoverable
+   */
+  isRecoverable() {
+    return false; // Override in subclasses
+  }
+}
+
+/**
+ * GitHub API related errors
+ */
+class GitHubAPIError extends InstallerError {
+  constructor(message, details = null, cause = null) {
+    const errorCode = GitHubAPIError.getErrorCode(details);
+    super(message, errorCode, details, cause);
+  }
+
+  static getErrorCode(details) {
+    if (details?.status === 403 && details?.headers?.['x-ratelimit-remaining'] === '0') {
+      return 'GITHUB_RATE_LIMIT';
+    }
+    if (details?.status === 404) {
+      return 'GITHUB_NOT_FOUND';
+    }
+    if (details?.status >= 500) {
+      return 'GITHUB_SERVER_ERROR';
+    }
+    if (details?.code === 'ENOTFOUND' || details?.code === 'ECONNREFUSED') {
+      return 'GITHUB_CONNECTION_ERROR';
+    }
+    return 'GITHUB_API_ERROR';
+  }
+
+  getUserMessage() {
+    switch (this.code) {
+    case 'GITHUB_RATE_LIMIT':
+      return 'GitHub API rate limit exceeded. Please wait a few minutes and try again, or use a GitHub token for higher limits.';
+    case 'GITHUB_NOT_FOUND':
+      return 'Repository or file not found on GitHub. Please check the repository URL and try again.';
+    case 'GITHUB_SERVER_ERROR':
+      return 'GitHub is experiencing server issues. Please try again in a few minutes.';
+    case 'GITHUB_CONNECTION_ERROR':
+      return 'Unable to connect to GitHub. Please check your internet connection and try again.';
+    default:
+      return 'Failed to fetch files from GitHub. Please try again or check your internet connection.';
+    }
+  }
+
+  isRecoverable() {
+    return ['GITHUB_RATE_LIMIT', 'GITHUB_SERVER_ERROR', 'GITHUB_CONNECTION_ERROR'].includes(this.code);
+  }
+}
+
+/**
+ * File system operation errors
+ */
+class FileSystemError extends InstallerError {
+  constructor(message, details = null, cause = null) {
+    const errorCode = FileSystemError.getErrorCode(details);
+    super(message, errorCode, details, cause);
+  }
+
+  static getErrorCode(details) {
+    if (details?.code === 'EACCES' || details?.code === 'EPERM') {
+      return 'FILESYSTEM_PERMISSION_DENIED';
+    }
+    if (details?.code === 'ENOENT') {
+      return 'FILESYSTEM_NOT_FOUND';
+    }
+    if (details?.code === 'EEXIST') {
+      return 'FILESYSTEM_ALREADY_EXISTS';
+    }
+    if (details?.code === 'ENOSPC') {
+      return 'FILESYSTEM_NO_SPACE';
+    }
+    if (details?.code === 'EMFILE' || details?.code === 'ENFILE') {
+      return 'FILESYSTEM_TOO_MANY_FILES';
+    }
+    return 'FILESYSTEM_ERROR';
+  }
+
+  getUserMessage() {
+    switch (this.code) {
+    case 'FILESYSTEM_PERMISSION_DENIED':
+      return 'Permission denied. Please run with appropriate permissions or choose a different directory.';
+    case 'FILESYSTEM_NOT_FOUND':
+      return 'Directory or file not found. Please check the path and try again.';
+    case 'FILESYSTEM_ALREADY_EXISTS':
+      return 'File or directory already exists. Use --force to overwrite or choose a different location.';
+    case 'FILESYSTEM_NO_SPACE':
+      return 'Not enough disk space to complete the installation.';
+    case 'FILESYSTEM_TOO_MANY_FILES':
+      return 'Too many open files. Please close some applications and try again.';
+    default:
+      return 'File system operation failed. Please check permissions and available space.';
+    }
+  }
+
+  isRecoverable() {
+    return ['FILESYSTEM_TOO_MANY_FILES'].includes(this.code);
+  }
+}
+
+/**
+ * Network related errors
+ */
+class NetworkError extends InstallerError {
+  constructor(message, details = null, cause = null) {
+    const errorCode = NetworkError.getErrorCode(details);
+    super(message, errorCode, details, cause);
+  }
+
+  static getErrorCode(details) {
+    if (details?.code === 'ENOTFOUND') {
+      return 'NETWORK_DNS_ERROR';
+    }
+    if (details?.code === 'ECONNREFUSED') {
+      return 'NETWORK_CONNECTION_REFUSED';
+    }
+    if (details?.code === 'ETIMEDOUT') {
+      return 'NETWORK_TIMEOUT';
+    }
+    if (details?.code === 'CERT_HAS_EXPIRED' || details?.code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE') {
+      return 'NETWORK_SSL_ERROR';
+    }
+    return 'NETWORK_ERROR';
+  }
+
+  getUserMessage() {
+    switch (this.code) {
+    case 'NETWORK_DNS_ERROR':
+      return 'DNS resolution failed. Please check your internet connection and DNS settings.';
+    case 'NETWORK_CONNECTION_REFUSED':
+      return 'Connection refused. The server may be down or unreachable.';
+    case 'NETWORK_TIMEOUT':
+      return 'Network request timed out. Please check your internet connection and try again.';
+    case 'NETWORK_SSL_ERROR':
+      return 'SSL certificate error. Please check your system time and certificate store.';
+    default:
+      return 'Network error occurred. Please check your internet connection and try again.';
+    }
+  }
+
+  isRecoverable() {
+    return ['NETWORK_TIMEOUT', 'NETWORK_CONNECTION_REFUSED'].includes(this.code);
+  }
+}
+
+/**
+ * Input validation errors
+ */
+class ValidationError extends InstallerError {
+  constructor(message, field = null, details = null) {
+    super(message, 'VALIDATION_ERROR', { field, ...details });
+    this.field = field;
+  }
+
+  getUserMessage() {
+    if (this.field) {
+      return `Invalid ${this.field}: ${this.message}`;
+    }
+    return `Validation error: ${this.message}`;
+  }
+
+  isRecoverable() {
+    return true; // User can correct input
+  }
+}
+
+/**
+ * Dependency check errors
+ */
+class DependencyError extends InstallerError {
+  constructor(message, dependency, details = null) {
+    super(message, 'DEPENDENCY_ERROR', { dependency, ...details });
+    this.dependency = dependency;
+  }
+
+  getUserMessage() {
+    return `Missing dependency: ${this.dependency}. ${this.message}`;
+  }
+
+  isRecoverable() {
+    return true; // User can install dependencies
+  }
+}
+
+/**
+ * User cancellation error
+ */
+class UserCancelledError extends InstallerError {
+  constructor(message = 'Installation cancelled by user') {
+    super(message, 'USER_CANCELLED');
+  }
+
+  getUserMessage() {
+    return this.message;
+  }
+
+  isRecoverable() {
+    return false;
+  }
+}
+
+/**
+ * Configuration errors
+ */
+class ConfigurationError extends InstallerError {
+  constructor(message, configKey = null, details = null) {
+    super(message, 'CONFIGURATION_ERROR', { configKey, ...details });
+    this.configKey = configKey;
+  }
+
+  getUserMessage() {
+    if (this.configKey) {
+      return `Configuration error in '${this.configKey}': ${this.message}`;
+    }
+    return `Configuration error: ${this.message}`;
+  }
+
+  isRecoverable() {
+    return true; // User can fix configuration
+  }
+}
+
+/**
+ * Error factory for creating appropriate error types
+ */
+class ErrorFactory {
+  /**
+   * Create an error from a caught exception
+   */
+  static fromCaught(error, context = null) {
+    if (error instanceof InstallerError) {
+      return error;
+    }
+
+    // Network errors
+    if (error.code && ['ENOTFOUND', 'ECONNREFUSED', 'ETIMEDOUT'].includes(error.code)) {
+      return new NetworkError(error.message, { code: error.code, context }, error);
+    }
+
+    // File system errors
+    if (error.code && ['EACCES', 'EPERM', 'ENOENT', 'EEXIST', 'ENOSPC'].includes(error.code)) {
+      return new FileSystemError(error.message, { code: error.code, context }, error);
+    }
+
+    // GitHub API errors (based on fetch response)
+    if (error.status || (context && context.includes('github'))) {
+      return new GitHubAPIError(error.message, { status: error.status, context }, error);
+    }
+
+    // Generic installer error
+    return new InstallerError(error.message, 'UNKNOWN_ERROR', { context }, error);
+  }
+
+  /**
+   * Create a GitHub API error
+   */
+  static github(message, details) {
+    return new GitHubAPIError(message, details);
+  }
+
+  /**
+   * Create a file system error
+   */
+  static filesystem(message, details) {
+    return new FileSystemError(message, details);
+  }
+
+  /**
+   * Create a network error
+   */
+  static network(message, details) {
+    return new NetworkError(message, details);
+  }
+
+  /**
+   * Create a validation error
+   */
+  static validation(message, field, details) {
+    return new ValidationError(message, field, details);
+  }
+
+  /**
+   * Create a dependency error
+   */
+  static dependency(message, dependency, details) {
+    return new DependencyError(message, dependency, details);
+  }
+
+  /**
+   * Create a user cancelled error
+   */
+  static userCancelled(message) {
+    return new UserCancelledError(message);
+  }
+
+  /**
+   * Create a configuration error
+   */
+  static configuration(message, configKey, details) {
+    return new ConfigurationError(message, configKey, details);
+  }
+}
+
+module.exports = {
+  InstallerError,
+  GitHubAPIError,
+  FileSystemError,
+  NetworkError,
+  ValidationError,
+  DependencyError,
+  UserCancelledError,
+  ConfigurationError,
+  ErrorFactory
+};

package/src/utils/index.js

@@ -0,0 +1,46 @@
+/**
+ * NPX Installer Utilities Module
+ * Centralized export for all utility functions and classes
+ */
+
+// Core utilities
+const logger = require('./logger');
+const errors = require('./errors');
+const platform = require('./platform');
+const config = require('./config');
+const retry = require('./retry');
+const constants = require('./constants');
+
+// Re-export all utilities for team integration
+module.exports = {
+  // Logger utilities
+  logger,
+  Logger: logger.Logger,
+
+  // Error handling
+  ...errors,
+  ErrorFactory: errors.ErrorFactory,
+
+  // Platform utilities
+  platform,
+  Platform: platform.Platform,
+
+  // Configuration management
+  config,
+  Config: config.Config,
+
+  // Retry mechanisms
+  retry: retry.retry,
+  RetryWrapper: retry.RetryWrapper,
+  CircuitBreaker: retry.CircuitBreaker,
+  retryPresets: retry.retryPresets,
+
+  // Constants and configuration
+  constants,
+
+  // Convenience exports for common patterns
+  GITHUB_URLS: constants.GITHUB_URLS,
+  ERROR_CODES: constants.ERROR_CODES,
+  FILE_PATHS: constants.FILE_PATHS,
+  RETRY_CONFIG: constants.RETRY_CONFIG
+};

package/src/utils/logger.js

@@ -0,0 +1,177 @@
+/**
+ * Logger utility for colored console output
+ * Provides consistent logging across the NPX installer with chalk-based colors
+ */
+
+const chalk = require('chalk');
+
+/**
+ * Log levels with corresponding colors and symbols
+ */
+const LOG_LEVELS = {
+  DEBUG: { color: chalk.gray, symbol: '🔧', level: 0 },
+  INFO: { color: chalk.blue, symbol: 'ℹ️', level: 1 },
+  SUCCESS: { color: chalk.green, symbol: '✅', level: 2 },
+  WARN: { color: chalk.yellow, symbol: '⚠️', level: 3 },
+  ERROR: { color: chalk.red, symbol: '❌', level: 4 },
+  SPINNER: { color: chalk.cyan, symbol: '⏳', level: 1 }
+};
+
+/**
+ * Logger class with colored output and level filtering
+ */
+class Logger {
+  constructor(options = {}) {
+    this.level = options.level || 'INFO';
+    this.prefix = options.prefix || '@claude-code/setup-installer';
+    this.timestamps = options.timestamps || false;
+    this.silent = options.silent || false;
+  }
+
+  /**
+   * Check if message should be logged based on level
+   */
+  shouldLog(messageLevel) {
+    if (this.silent) return false;
+    const currentLevel = LOG_LEVELS[this.level]?.level || 1;
+    const msgLevel = LOG_LEVELS[messageLevel]?.level || 1;
+    return msgLevel >= currentLevel;
+  }
+
+  /**
+   * Format a log message with prefix, timestamp, and color
+   */
+  formatMessage(level, message, data = null) {
+    const config = LOG_LEVELS[level] || LOG_LEVELS.INFO;
+    const timestamp = this.timestamps ? chalk.gray(`[${new Date().toISOString()}]`) : '';
+    const prefix = chalk.bold(`[${this.prefix}]`);
+    const symbol = config.symbol;
+    const coloredMessage = config.color(message);
+
+    let formatted = `${timestamp} ${prefix} ${symbol} ${coloredMessage}`;
+
+    if (data) {
+      formatted += '\n' + this.formatData(data);
+    }
+
+    return formatted;
+  }
+
+  /**
+   * Format additional data for logging
+   */
+  formatData(data) {
+    if (typeof data === 'object') {
+      return chalk.gray(JSON.stringify(data, null, 2));
+    }
+    return chalk.gray(String(data));
+  }
+
+  /**
+   * Log a debug message
+   */
+  debug(message, data) {
+    if (this.shouldLog('DEBUG')) {
+      console.log(this.formatMessage('DEBUG', message, data));
+    }
+  }
+
+  /**
+   * Log an info message
+   */
+  info(message, data) {
+    if (this.shouldLog('INFO')) {
+      console.log(this.formatMessage('INFO', message, data));
+    }
+  }
+
+  /**
+   * Log a success message
+   */
+  success(message, data) {
+    if (this.shouldLog('SUCCESS')) {
+      console.log(this.formatMessage('SUCCESS', message, data));
+    }
+  }
+
+  /**
+   * Log a warning message
+   */
+  warn(message, data) {
+    if (this.shouldLog('WARN')) {
+      console.warn(this.formatMessage('WARN', message, data));
+    }
+  }
+
+  /**
+   * Log an error message
+   */
+  error(message, data) {
+    if (this.shouldLog('ERROR')) {
+      console.error(this.formatMessage('ERROR', message, data));
+    }
+  }
+
+  /**
+   * Log a spinner/progress message
+   */
+  spinner(message, data) {
+    if (this.shouldLog('SPINNER')) {
+      console.log(this.formatMessage('SPINNER', message, data));
+    }
+  }
+
+  /**
+   * Create a new logger with different options
+   */
+  child(options) {
+    return new Logger({
+      level: this.level,
+      prefix: this.prefix,
+      timestamps: this.timestamps,
+      silent: this.silent,
+      ...options
+    });
+  }
+
+  /**
+   * Set the log level
+   */
+  setLevel(level) {
+    if (LOG_LEVELS[level]) {
+      this.level = level;
+    } else {
+      this.warn(`Invalid log level: ${level}. Using INFO instead.`);
+    }
+  }
+
+  /**
+   * Enable or disable silent mode
+   */
+  setSilent(silent) {
+    this.silent = silent;
+  }
+}
+
+/**
+ * Default logger instance
+ */
+const defaultLogger = new Logger();
+
+/**
+ * Convenience functions using default logger
+ */
+const logger = {
+  debug: (msg, data) => defaultLogger.debug(msg, data),
+  info: (msg, data) => defaultLogger.info(msg, data),
+  success: (msg, data) => defaultLogger.success(msg, data),
+  warn: (msg, data) => defaultLogger.warn(msg, data),
+  error: (msg, data) => defaultLogger.error(msg, data),
+  spinner: (msg, data) => defaultLogger.spinner(msg, data),
+  setLevel: (level) => defaultLogger.setLevel(level),
+  setSilent: (silent) => defaultLogger.setSilent(silent),
+  child: (options) => defaultLogger.child(options),
+  Logger
+};
+
+module.exports = logger;