@fenwave/agent 1.1.0

package/utils/errorHandler.js

@@ -0,0 +1,327 @@
+import chalk from 'chalk';
+
+/**
+ * Error codes for common errors
+ */
+export const ErrorCode = {
+  // Network errors
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  BACKEND_UNREACHABLE: 'BACKEND_UNREACHABLE',
+  TIMEOUT: 'TIMEOUT',
+
+  // Authentication errors
+  INVALID_TOKEN: 'INVALID_TOKEN',
+  TOKEN_EXPIRED: 'TOKEN_EXPIRED',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
+
+  // Registration errors
+  REGISTRATION_FAILED: 'REGISTRATION_FAILED',
+  DEVICE_ALREADY_REGISTERED: 'DEVICE_ALREADY_REGISTERED',
+  RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED',
+
+  // Prerequisites errors
+  DOCKER_NOT_INSTALLED: 'DOCKER_NOT_INSTALLED',
+  DOCKER_NOT_RUNNING: 'DOCKER_NOT_RUNNING',
+  NODE_VERSION_MISMATCH: 'NODE_VERSION_MISMATCH',
+  AWS_CLI_NOT_INSTALLED: 'AWS_CLI_NOT_INSTALLED',
+
+  // File system errors
+  PERMISSION_DENIED: 'PERMISSION_DENIED',
+  FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+  DIRECTORY_CREATE_FAILED: 'DIRECTORY_CREATE_FAILED',
+
+  // Docker errors
+  DOCKER_PULL_FAILED: 'DOCKER_PULL_FAILED',
+  ECR_AUTH_FAILED: 'ECR_AUTH_FAILED',
+  CONTAINER_START_FAILED: 'CONTAINER_START_FAILED',
+
+  // Generic errors
+  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+  OPERATION_CANCELLED: 'OPERATION_CANCELLED',
+};
+
+/**
+ * User-friendly error messages and suggestions
+ */
+const ERROR_MESSAGES = {
+  [ErrorCode.NETWORK_ERROR]: {
+    message: 'Network error occurred',
+    suggestion: 'Check your internet connection and try again.',
+  },
+  [ErrorCode.BACKEND_UNREACHABLE]: {
+    message: 'Cannot connect to Backstage backend',
+    suggestion:
+      'Make sure Backstage is running and accessible. Check the backend URL in your configuration.',
+  },
+  [ErrorCode.TIMEOUT]: {
+    message: 'Operation timed out',
+    suggestion: 'The operation took too long. Check your network connection and try again.',
+  },
+  [ErrorCode.INVALID_TOKEN]: {
+    message: 'Invalid registration token',
+    suggestion:
+      'Get a new registration token from Backstage at /agent-installer and try again.',
+  },
+  [ErrorCode.TOKEN_EXPIRED]: {
+    message: 'Registration token has expired',
+    suggestion:
+      'Tokens are valid for 7 days. Get a new token from Backstage at /agent-installer.',
+  },
+  [ErrorCode.UNAUTHORIZED]: {
+    message: 'Authentication failed',
+    suggestion: 'Run "fenwave login" to authenticate with Backstage.',
+  },
+  [ErrorCode.INVALID_CREDENTIALS]: {
+    message: 'Invalid device credentials',
+    suggestion:
+      'Your device credentials may have been revoked or are invalid. Run "fenwave register" to re-register your device.',
+  },
+  [ErrorCode.REGISTRATION_FAILED]: {
+    message: 'Device registration failed',
+    suggestion:
+      'Check your registration token and try again. If the problem persists, contact support.',
+  },
+  [ErrorCode.DEVICE_ALREADY_REGISTERED]: {
+    message: 'Device is already registered',
+    suggestion:
+      'This device is already registered. Use "fenwave status" to check registration details.',
+  },
+  [ErrorCode.RATE_LIMIT_EXCEEDED]: {
+    message: 'Rate limit exceeded',
+    suggestion: 'Too many requests. Please wait a few minutes and try again.',
+  },
+  [ErrorCode.DOCKER_NOT_INSTALLED]: {
+    message: 'Docker is not installed',
+    suggestion: 'Install Docker Desktop from https://www.docker.com/products/docker-desktop',
+  },
+  [ErrorCode.DOCKER_NOT_RUNNING]: {
+    message: 'Docker is not running',
+    suggestion: 'Start Docker Desktop and try again.',
+  },
+  [ErrorCode.NODE_VERSION_MISMATCH]: {
+    message: 'Node.js version is too old',
+    suggestion: 'Install Node.js v18 or higher from https://nodejs.org',
+  },
+  [ErrorCode.AWS_CLI_NOT_INSTALLED]: {
+    message: 'AWS CLI is not installed',
+    suggestion: 'Install AWS CLI from https://aws.amazon.com/cli/',
+  },
+  [ErrorCode.PERMISSION_DENIED]: {
+    message: 'Permission denied',
+    suggestion:
+      'You do not have permission to perform this operation. Try running with appropriate permissions.',
+  },
+  [ErrorCode.FILE_NOT_FOUND]: {
+    message: 'File not found',
+    suggestion: 'The required file was not found. Try re-installing the agent.',
+  },
+  [ErrorCode.DIRECTORY_CREATE_FAILED]: {
+    message: 'Failed to create directory',
+    suggestion: 'Check file system permissions and available disk space.',
+  },
+  [ErrorCode.DOCKER_PULL_FAILED]: {
+    message: 'Failed to pull Docker image',
+    suggestion:
+      'Check your Docker registry authentication and network connection. Try running "docker login" if using a private registry.',
+  },
+  [ErrorCode.ECR_AUTH_FAILED]: {
+    message: 'AWS ECR authentication failed',
+    suggestion:
+      'Configure your AWS credentials using "aws configure" or check your AWS access.',
+  },
+  [ErrorCode.CONTAINER_START_FAILED]: {
+    message: 'Failed to start container',
+    suggestion: 'Check Docker logs for details: docker logs <container-id>',
+  },
+  [ErrorCode.UNKNOWN_ERROR]: {
+    message: 'An unknown error occurred',
+    suggestion: 'Check the error details above. If the problem persists, contact support.',
+  },
+  [ErrorCode.OPERATION_CANCELLED]: {
+    message: 'Operation cancelled by user',
+    suggestion: null,
+  },
+};
+
+/**
+ * Parse error and determine error code
+ *
+ * @param {Error} error - Error object
+ * @returns {string} Error code
+ */
+function getErrorCode(error) {
+  // Check for network errors
+  if (error.code === 'ECONNREFUSED' || error.code === 'ENOTFOUND') {
+    return ErrorCode.BACKEND_UNREACHABLE;
+  }
+
+  if (error.code === 'ETIMEDOUT' || error.code === 'ESOCKETTIMEDOUT') {
+    return ErrorCode.TIMEOUT;
+  }
+
+  if (error.code === 'EACCES' || error.code === 'EPERM') {
+    return ErrorCode.PERMISSION_DENIED;
+  }
+
+  if (error.code === 'ENOENT') {
+    return ErrorCode.FILE_NOT_FOUND;
+  }
+
+  // Check for HTTP status codes
+  if (error.response) {
+    const status = error.response.status;
+
+    if (status === 401) {
+      const errorMessage = error.response.data?.error || '';
+      if (errorMessage.includes('token')) {
+        if (errorMessage.includes('expired')) {
+          return ErrorCode.TOKEN_EXPIRED;
+        }
+        return ErrorCode.INVALID_TOKEN;
+      }
+      return ErrorCode.UNAUTHORIZED;
+    }
+
+    if (status === 429) {
+      return ErrorCode.RATE_LIMIT_EXCEEDED;
+    }
+
+    if (status >= 500) {
+      return ErrorCode.BACKEND_UNREACHABLE;
+    }
+  }
+
+  // Check error message for specific patterns
+  const message = error.message?.toLowerCase() || '';
+
+  if (message.includes('invalid') && message.includes('token')) {
+    return ErrorCode.INVALID_TOKEN;
+  }
+
+  if (message.includes('expired') && message.includes('token')) {
+    return ErrorCode.TOKEN_EXPIRED;
+  }
+
+  if (message.includes('docker') && message.includes('not installed')) {
+    return ErrorCode.DOCKER_NOT_INSTALLED;
+  }
+
+  if (message.includes('docker') && message.includes('not running')) {
+    return ErrorCode.DOCKER_NOT_RUNNING;
+  }
+
+  if (message.includes('ecr') && message.includes('auth')) {
+    return ErrorCode.ECR_AUTH_FAILED;
+  }
+
+  return ErrorCode.UNKNOWN_ERROR;
+}
+
+/**
+ * Handle error and display user-friendly message
+ *
+ * @param {Error} error - Error object
+ * @param {string} context - Context where error occurred (optional)
+ */
+export function handleError(error, context) {
+  const errorCode = getErrorCode(error);
+  const errorInfo = ERROR_MESSAGES[errorCode] || ERROR_MESSAGES[ErrorCode.UNKNOWN_ERROR];
+
+  console.log('');
+  console.log(chalk.red('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+  console.log(chalk.red.bold('❌ Error'));
+  console.log(chalk.red('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+
+  if (context) {
+    console.log(chalk.gray(`Context: ${context}`));
+  }
+
+  console.log(chalk.red(`\n${errorInfo.message}`));
+
+  if (errorInfo.suggestion) {
+    console.log(chalk.yellow(`\n💡 Suggestion: ${errorInfo.suggestion}`));
+  }
+
+  // Display technical details in verbose mode
+  if (process.env.FW_VERBOSE === 'true' || process.env.DEBUG === 'true') {
+    console.log(chalk.gray('\n--- Technical Details ---'));
+    console.log(chalk.gray(`Error Code: ${errorCode}`));
+    console.log(chalk.gray(`Message: ${error.message}`));
+
+    if (error.stack) {
+      console.log(chalk.gray(`Stack Trace:\n${error.stack}`));
+    }
+
+    if (error.response) {
+      console.log(chalk.gray(`HTTP Status: ${error.response.status}`));
+      console.log(chalk.gray(`Response: ${JSON.stringify(error.response.data, null, 2)}`));
+    }
+  }
+
+  console.log(chalk.red('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+  console.log('');
+}
+
+/**
+ * Create a custom error with error code
+ *
+ * @param {string} errorCode - Error code
+ * @param {string} details - Additional details
+ * @returns {Error} Custom error
+ */
+export function createError(errorCode, details) {
+  const error = new Error(ERROR_MESSAGES[errorCode]?.message || 'Unknown error');
+  error.code = errorCode;
+  error.details = details;
+  return error;
+}
+
+/**
+ * Display a simple error message without full error handling
+ *
+ * @param {string} message - Error message
+ */
+export function displaySimpleError(message) {
+  console.log(chalk.red('❌ ' + message));
+}
+
+/**
+ * Display warning
+ *
+ * @param {string} message - Warning message
+ */
+export function displayWarning(message) {
+  console.log(chalk.yellow('⚠️  ' + message));
+}
+
+/**
+ * Check if error is a user cancellation
+ *
+ * @param {Error} error - Error to check
+ * @returns {boolean} True if user cancelled
+ */
+export function isUserCancellation(error) {
+  return (
+    error.code === ErrorCode.OPERATION_CANCELLED ||
+    error.message?.toLowerCase().includes('cancelled') ||
+    error.message?.toLowerCase().includes('abort')
+  );
+}
+
+/**
+ * Get help command for error code
+ *
+ * @param {string} errorCode - Error code
+ * @returns {string|null} Help command or null
+ */
+export function getHelpCommand(errorCode) {
+  const helpCommands = {
+    [ErrorCode.INVALID_TOKEN]: 'fenwave help register',
+    [ErrorCode.DOCKER_NOT_INSTALLED]: 'fenwave help prerequisites',
+    [ErrorCode.DOCKER_NOT_RUNNING]: 'fenwave help prerequisites',
+    [ErrorCode.UNAUTHORIZED]: 'fenwave help login',
+  };
+
+  return helpCommands[errorCode] || null;
+}

package/utils/prerequisites.js

@@ -0,0 +1,323 @@
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+
+/**
+ * Check if a command exists
+ *
+ * @param {string} command - Command to check
+ * @returns {boolean} True if command exists
+ */
+function commandExists(command) {
+  try {
+    execSync(`command -v ${command}`, { stdio: 'ignore' });
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Get command version
+ *
+ * @param {string} command - Command to check
+ * @param {string} versionFlag - Flag to get version (default: --version)
+ * @returns {string|null} Version string or null if not found
+ */
+function getCommandVersion(command, versionFlag = '--version') {
+  try {
+    const output = execSync(`${command} ${versionFlag}`, { encoding: 'utf8', stdio: 'pipe' });
+    return output.trim().split('\n')[0];
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Check if Docker is installed and running
+ *
+ * @returns {Object} Docker status
+ */
+function checkDocker() {
+  const installed = commandExists('docker');
+
+  if (!installed) {
+    return {
+      name: 'Docker',
+      installed: false,
+      running: false,
+      version: null,
+      downloadUrl: 'https://www.docker.com/products/docker-desktop',
+    };
+  }
+
+  const version = getCommandVersion('docker', '--version');
+
+  // Check if Docker daemon is running
+  let running = false;
+  try {
+    execSync('docker info', { stdio: 'ignore' });
+    running = true;
+  } catch (error) {
+    running = false;
+  }
+
+  return {
+    name: 'Docker',
+    installed: true,
+    running,
+    version,
+    downloadUrl: 'https://www.docker.com/products/docker-desktop',
+  };
+}
+
+/**
+ * Check if Node.js is installed and meets minimum version
+ *
+ * @returns {Object} Node.js status
+ */
+function checkNode() {
+  const installed = commandExists('node');
+
+  if (!installed) {
+    return {
+      name: 'Node.js',
+      installed: false,
+      version: null,
+      meetsRequirement: false,
+      minVersion: '18.0.0',
+      downloadUrl: 'https://nodejs.org',
+    };
+  }
+
+  const version = getCommandVersion('node', '--version');
+
+  // Extract major version number
+  const majorVersion = version ? parseInt(version.replace('v', '').split('.')[0], 10) : 0;
+  const meetsRequirement = majorVersion >= 18;
+
+  return {
+    name: 'Node.js',
+    installed: true,
+    version,
+    meetsRequirement,
+    minVersion: '18.0.0',
+    downloadUrl: 'https://nodejs.org',
+  };
+}
+
+/**
+ * Check if AWS CLI is installed
+ *
+ * @returns {Object} AWS CLI status
+ */
+function checkAwsCli() {
+  const installed = commandExists('aws');
+
+  if (!installed) {
+    return {
+      name: 'AWS CLI',
+      installed: false,
+      version: null,
+      downloadUrl: 'https://aws.amazon.com/cli/',
+    };
+  }
+
+  const version = getCommandVersion('aws', '--version');
+
+  return {
+    name: 'AWS CLI',
+    installed: true,
+    version,
+    downloadUrl: 'https://aws.amazon.com/cli/',
+  };
+}
+
+/**
+ * Check network connectivity to Backstage backend
+ *
+ * @param {string} backendUrl - Backend URL to check
+ * @returns {Promise<Object>} Connectivity status
+ */
+async function checkBackendConnectivity(backendUrl) {
+  try {
+    const axios = (await import('axios')).default;
+
+    // Try to reach the backend health endpoint or root
+    const response = await axios.get(`${backendUrl}/api/agent-cli/health`, {
+      timeout: 5000,
+      validateStatus: () => true, // Accept any status
+    });
+
+    return {
+      name: 'Backstage Backend',
+      reachable: response.status < 500,
+      url: backendUrl,
+      status: response.status,
+    };
+  } catch (error) {
+    return {
+      name: 'Backstage Backend',
+      reachable: false,
+      url: backendUrl,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Run all prerequisite checks
+ *
+ * @param {Object} options - Check options
+ * @param {string} options.backendUrl - Backend URL for connectivity check
+ * @param {boolean} options.verbose - Show detailed output
+ * @returns {Promise<Object>} Check results
+ */
+export async function checkPrerequisites(options = {}) {
+  const { backendUrl, verbose = false } = options;
+
+  const results = {
+    docker: checkDocker(),
+    node: checkNode(),
+    awsCli: checkAwsCli(),
+  };
+
+  // Check backend connectivity if URL provided
+  if (backendUrl) {
+    results.backend = await checkBackendConnectivity(backendUrl);
+  }
+
+  // Calculate overall status
+  const allPassed =
+    results.docker.installed &&
+    results.docker.running &&
+    results.node.installed &&
+    results.node.meetsRequirement &&
+    results.awsCli.installed &&
+    (!backendUrl || results.backend?.reachable);
+
+  return {
+    results,
+    allPassed,
+  };
+}
+
+/**
+ * Display prerequisite check results
+ *
+ * @param {Object} checkResults - Results from checkPrerequisites()
+ */
+export function displayPrerequisites(checkResults) {
+  const { results, allPassed } = checkResults;
+
+  console.log('\n' + chalk.bold('📋 Prerequisites Check:\n'));
+
+  // Docker
+  if (results.docker.installed && results.docker.running) {
+    console.log(chalk.green('  ✅ Docker') + ` (${results.docker.version})`);
+  } else if (results.docker.installed && !results.docker.running) {
+    console.log(chalk.yellow('  ⚠️  Docker') + ` (installed but not running)`);
+    console.log(chalk.yellow('     Please start Docker Desktop'));
+  } else {
+    console.log(chalk.red('  ❌ Docker') + ' (not installed)');
+    console.log(chalk.gray(`     Download: ${results.docker.downloadUrl}`));
+  }
+
+  // Node.js
+  if (results.node.installed && results.node.meetsRequirement) {
+    console.log(chalk.green('  ✅ Node.js') + ` (${results.node.version})`);
+  } else if (results.node.installed && !results.node.meetsRequirement) {
+    console.log(chalk.yellow('  ⚠️  Node.js') + ` (${results.node.version}, requires ${results.node.minVersion}+)`);
+    console.log(chalk.gray(`     Download: ${results.node.downloadUrl}`));
+  } else {
+    console.log(chalk.red('  ❌ Node.js') + ' (not installed)');
+    console.log(chalk.gray(`     Download: ${results.node.downloadUrl}`));
+  }
+
+  // AWS CLI
+  if (results.awsCli.installed) {
+    console.log(chalk.green('  ✅ AWS CLI') + ` (${results.awsCli.version})`);
+  } else {
+    console.log(chalk.red('  ❌ AWS CLI') + ' (not installed)');
+    console.log(chalk.gray(`     Download: ${results.awsCli.downloadUrl}`));
+  }
+
+  // Backend connectivity
+  if (results.backend) {
+    if (results.backend.reachable) {
+      console.log(chalk.green('  ✅ Backstage Backend') + ` (${results.backend.url})`);
+    } else {
+      console.log(chalk.red('  ❌ Backstage Backend') + ' (not reachable)');
+      console.log(chalk.gray(`     URL: ${results.backend.url}`));
+      if (results.backend.error) {
+        console.log(chalk.gray(`     Error: ${results.backend.error}`));
+      }
+    }
+  }
+
+  console.log('');
+
+  if (allPassed) {
+    console.log(chalk.green('✅ All prerequisites met!\n'));
+  } else {
+    console.log(chalk.yellow('⚠️  Some prerequisites are missing or not running.\n'));
+  }
+
+  return allPassed;
+}
+
+/**
+ * Get missing prerequisites as a list
+ *
+ * @param {Object} checkResults - Results from checkPrerequisites()
+ * @returns {Array} List of missing prerequisites
+ */
+export function getMissingPrerequisites(checkResults) {
+  const { results } = checkResults;
+  const missing = [];
+
+  if (!results.docker.installed) {
+    missing.push({
+      name: 'Docker',
+      reason: 'Not installed',
+      action: `Install from ${results.docker.downloadUrl}`,
+    });
+  } else if (!results.docker.running) {
+    missing.push({
+      name: 'Docker',
+      reason: 'Not running',
+      action: 'Start Docker Desktop',
+    });
+  }
+
+  if (!results.node.installed) {
+    missing.push({
+      name: 'Node.js',
+      reason: 'Not installed',
+      action: `Install from ${results.node.downloadUrl}`,
+    });
+  } else if (!results.node.meetsRequirement) {
+    missing.push({
+      name: 'Node.js',
+      reason: `Version ${results.node.version} is too old (requires ${results.node.minVersion}+)`,
+      action: `Update from ${results.node.downloadUrl}`,
+    });
+  }
+
+  if (!results.awsCli.installed) {
+    missing.push({
+      name: 'AWS CLI',
+      reason: 'Not installed',
+      action: `Install from ${results.awsCli.downloadUrl}`,
+    });
+  }
+
+  if (results.backend && !results.backend.reachable) {
+    missing.push({
+      name: 'Backstage Backend',
+      reason: 'Not reachable',
+      action: `Check network connection and URL: ${results.backend.url}`,
+    });
+  }
+
+  return missing;
+}