@intranefr/superbackend 1.7.7 → 1.7.9

package/autochangelog-cli/src/cli/utils/config.js

@@ -0,0 +1,277 @@
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Configuration utilities for CLI operations
+ * Handles environment variables, config files, and global settings
+ */
+
+// Default configuration
+const DEFAULT_CONFIG = {
+  // Database
+  mongodb_uri: process.env.MONGODB_URI || 'mongodb://localhost:27017/autochangelog',
+  
+  // GitHub
+  github_client_id: process.env.GITHUB_CLIENT_ID,
+  github_client_secret: process.env.GITHUB_CLIENT_SECRET,
+  github_token: process.env.GITHUB_TOKEN,
+  
+  // Authentication
+  jwt_secret: process.env.JWT_SECRET || 'autochangelog-cli-secret',
+  
+  // API
+  api_base_url: process.env.API_BASE_URL || 'http://localhost:3000',
+  
+  // CLI
+  output_format: process.env.OUTPUT_FORMAT || 'auto', // auto, json, text
+  color_enabled: process.env.COLOR !== 'false',
+  verbose: process.env.VERBOSE === 'true',
+  timeout: parseInt(process.env.TIMEOUT) || 30000,
+  
+  // Paths
+  config_path: process.env.CONFIG_PATH || path.join(os.homedir(), '.autochangelog', 'config.json'),
+  cache_path: process.env.CACHE_PATH || path.join(os.homedir(), '.autochangelog', 'cache'),
+};
+
+/**
+ * Get configuration value with environment variable override
+ * @param {string} key - Configuration key
+ * @param {string} envVar - Environment variable name
+ * @param {*} defaultValue - Default value
+ * @returns {*} Configuration value
+ */
+function getConfigValue(key, envVar, defaultValue) {
+  const envValue = process.env[envVar];
+  if (envValue !== undefined) {
+    return envValue;
+  }
+  
+  // Try to load from config file
+  try {
+    const configPath = DEFAULT_CONFIG.config_path;
+    if (fs.existsSync(configPath)) {
+      const config = fs.readJsonSync(configPath);
+      return config[key] !== undefined ? config[key] : defaultValue;
+    }
+  } catch (error) {
+    // Config file exists but is invalid, ignore and use defaults
+  }
+  
+  return defaultValue;
+}
+
+/**
+ * Load configuration from environment and config file
+ * @returns {Object} Configuration object
+ */
+function loadConfig() {
+  const config = { ...DEFAULT_CONFIG };
+  
+  // Load from config file if exists
+  try {
+    if (fs.existsSync(config.config_path)) {
+      const fileConfig = fs.readJsonSync(config.config_path);
+      Object.assign(config, fileConfig);
+    }
+  } catch (error) {
+    // Config file exists but is invalid, ignore and use defaults
+  }
+  
+  // Override with environment variables
+  config.mongodb_uri = getConfigValue('mongodb_uri', 'MONGODB_URI');
+  config.github_client_id = getConfigValue('github_client_id', 'GITHUB_CLIENT_ID');
+  config.github_client_secret = getConfigValue('github_client_secret', 'GITHUB_CLIENT_SECRET');
+  config.github_token = getConfigValue('github_token', 'GITHUB_TOKEN');
+  config.jwt_secret = getConfigValue('jwt_secret', 'JWT_SECRET');
+  config.api_base_url = getConfigValue('api_base_url', 'API_BASE_URL');
+  config.output_format = getConfigValue('output_format', 'OUTPUT_FORMAT');
+  config.color_enabled = getConfigValue('color_enabled', 'COLOR') !== false;
+  config.verbose = getConfigValue('verbose', 'VERBOSE');
+  config.timeout = parseInt(getConfigValue('timeout', 'TIMEOUT', '30000'));
+  
+  return config;
+}
+
+/**
+ * Save configuration to file
+ * @param {Object} updates - Configuration updates to save
+ */
+function saveConfig(updates) {
+  const configPath = DEFAULT_CONFIG.config_path;
+  
+  // Ensure config directory exists
+  fs.ensureDirSync(path.dirname(configPath));
+  
+  // Load existing config
+  let config = {};
+  try {
+    if (fs.existsSync(configPath)) {
+      config = fs.readJsonSync(configPath);
+    }
+  } catch (error) {
+    // Config file exists but is invalid, start fresh
+  }
+  
+  // Apply updates
+  Object.assign(config, updates);
+  
+  // Save config
+  fs.writeJsonSync(configPath, config, { spaces: 2 });
+}
+
+/**
+ * Clear saved configuration
+ */
+function clearConfig() {
+  const configPath = DEFAULT_CONFIG.config_path;
+  if (fs.existsSync(configPath)) {
+    fs.removeSync(configPath);
+  }
+}
+
+/**
+ * Get authentication token from various sources
+ * @returns {string|null} Authentication token
+ */
+function getAuthToken() {
+  // Check environment variable first
+  if (process.env.GITHUB_TOKEN) {
+    return process.env.GITHUB_TOKEN;
+  }
+  
+  // Check config file
+  try {
+    if (fs.existsSync(DEFAULT_CONFIG.config_path)) {
+      const config = fs.readJsonSync(DEFAULT_CONFIG.config_path);
+      if (config.github_token) {
+        return config.github_token;
+      }
+    }
+  } catch (error) {
+    // Config file exists but is invalid
+  }
+  
+  return null;
+}
+
+/**
+ * Set authentication token
+ * @param {string} token - GitHub token
+ */
+function setAuthToken(token) {
+  saveConfig({ github_token: token });
+}
+
+/**
+ * Clear authentication token
+ */
+function clearAuthToken() {
+  const config = loadConfig();
+  delete config.github_token;
+  saveConfig(config);
+}
+
+/**
+ * Check if user is authenticated
+ * @returns {boolean} True if authenticated
+ */
+function isAuthenticated() {
+  return !!getAuthToken();
+}
+
+/**
+ * Setup global options for all commands
+ * @param {Object} program - Commander program instance
+ */
+function setupGlobalOptions(program) {
+  program
+    .option('--json', 'Output in JSON format (default in non-TTY)')
+    .option('--verbose', 'Enable verbose logging')
+    .option('--no-color', 'Disable colored output')
+    .option('--config <path>', 'Path to config file')
+    .option('--timeout <ms>', 'Request timeout in milliseconds', parseInt);
+}
+
+/**
+ * Handle global errors and exit gracefully
+ * @param {Object} logger - Logger instance
+ */
+function handleGlobalErrors(logger) {
+  // Handle uncaught exceptions
+  process.on('uncaughtException', (error) => {
+    logger.error('Uncaught Exception:', error);
+    process.exit(1);
+  });
+
+  // Handle unhandled promise rejections
+  process.on('unhandledRejection', (reason, promise) => {
+    logger.error('Unhandled Promise Rejection at:', promise, 'reason:', reason);
+    process.exit(1);
+  });
+
+  // Handle SIGINT (Ctrl+C)
+  process.on('SIGINT', () => {
+    logger.info('Received SIGINT, exiting...');
+    process.exit(0);
+  });
+
+  // Handle SIGTERM
+  process.on('SIGTERM', () => {
+    logger.info('Received SIGTERM, exiting...');
+    process.exit(0);
+  });
+}
+
+/**
+ * Validate required environment variables
+ * @param {Array} required - Array of required environment variable names
+ * @returns {Array} Array of missing environment variables
+ */
+function validateEnvironment(required = []) {
+  const missing = [];
+  
+  required.forEach(envVar => {
+    if (!process.env[envVar]) {
+      missing.push(envVar);
+    }
+  });
+  
+  return missing;
+}
+
+/**
+ * Get cache directory path
+ * @returns {string} Cache directory path
+ */
+function getCacheDir() {
+  const cachePath = DEFAULT_CONFIG.cache_path;
+  fs.ensureDirSync(cachePath);
+  return cachePath;
+}
+
+/**
+ * Clear cache directory
+ */
+function clearCache() {
+  const cachePath = DEFAULT_CONFIG.cache_path;
+  if (fs.existsSync(cachePath)) {
+    fs.emptyDirSync(cachePath);
+  }
+}
+
+module.exports = {
+  DEFAULT_CONFIG,
+  loadConfig,
+  saveConfig,
+  clearConfig,
+  getAuthToken,
+  setAuthToken,
+  clearAuthToken,
+  isAuthenticated,
+  setupGlobalOptions,
+  handleGlobalErrors,
+  validateEnvironment,
+  getCacheDir,
+  clearCache,
+};

package/autochangelog-cli/src/cli/utils/errors.js

@@ -0,0 +1,307 @@
+const chalk = require('chalk');
+
+/**
+ * Error handling utilities for CLI operations
+ * Provides structured error responses following agent-friendly patterns
+ */
+
+// Error code constants following the documented pattern
+const ERROR_CODES = {
+  // User errors (80-89)
+  INVALID_ARGUMENT: 85,
+  RESOURCE_NOT_FOUND: 92,
+  AUTHENTICATION_FAILED: 93,
+  PERMISSION_DENIED: 94,
+  
+  // Resource/state errors (90-99)
+  RESOURCE_EXISTS: 95,
+  CONFLICT: 96,
+  
+  // Integration/external errors (100-109)
+  GITHUB_API_ERROR: 105,
+  NETWORK_ERROR: 106,
+  TIMEOUT_ERROR: 107,
+  RATE_LIMIT_EXCEEDED: 108,
+  
+  // Internal software errors (110-119)
+  INTERNAL_ERROR: 110,
+  DATABASE_ERROR: 111,
+  VALIDATION_ERROR: 112,
+};
+
+/**
+ * Create a structured error response
+ * @param {string} message - Human-readable error message
+ * @param {string} type - Machine-readable error type
+ * @param {number} code - Semantic error code
+ * @param {Object} details - Additional error details
+ * @param {Array} suggestions - Array of suggested next actions
+ * @param {boolean} recoverable - Whether the error is recoverable
+ * @param {number} retryAfter - Seconds to wait before retry (for rate limits/timeouts)
+ * @returns {Object} Structured error object
+ */
+function createError(message, type, code, details = {}, suggestions = [], recoverable = false, retryAfter = null) {
+  return {
+    error: {
+      message,
+      type,
+      code,
+      details,
+      suggestions,
+      recoverable,
+      retry_after: retryAfter,
+      timestamp: new Date().toISOString(),
+    }
+  };
+}
+
+/**
+ * Handle CLI errors with appropriate exit codes and output
+ * @param {Error} error - The error to handle
+ * @param {Object} output - Output manager instance
+ */
+function handleCliError(error, output) {
+  let structuredError;
+  
+  // Handle different error types
+  if (error.code && error.type) {
+    // Already structured error
+    structuredError = error;
+  } else if (error.name === 'ValidationError') {
+    structuredError = createError(
+      error.message || 'Validation failed',
+      'validation_error',
+      ERROR_CODES.VALIDATION_ERROR,
+      error.details || {},
+      ['Check input parameters and try again'],
+      false
+    );
+  } else if (error.name === 'MongoError' || error.name === 'MongooseError') {
+    structuredError = createError(
+      error.message || 'Database operation failed',
+      'database_error',
+      ERROR_CODES.DATABASE_ERROR,
+      { originalError: error.message },
+      ['Check database connection and try again'],
+      true,
+      5
+    );
+  } else if (error.response && error.response.status) {
+    // HTTP error from GitHub API
+    const status = error.response.status;
+    if (status === 401) {
+      structuredError = createError(
+        'Authentication failed. Check GitHub token permissions.',
+        'authentication_failed',
+        ERROR_CODES.AUTHENTICATION_FAILED,
+        { status, message: error.message },
+        ['Run "autochangelog auth login" to re-authenticate'],
+        false
+      );
+    } else if (status === 403) {
+      structuredError = createError(
+        'Access denied. Check repository permissions.',
+        'permission_denied',
+        ERROR_CODES.PERMISSION_DENIED,
+        { status, message: error.message },
+        ['Check GitHub token has repo access', 'Verify repository visibility'],
+        false
+      );
+    } else if (status === 404) {
+      structuredError = createError(
+        'Resource not found',
+        'resource_not_found',
+        ERROR_CODES.RESOURCE_NOT_FOUND,
+        { status, message: error.message },
+        ['Check resource ID or name', 'Verify resource exists'],
+        false
+      );
+    } else if (status === 429) {
+      structuredError = createError(
+        'Rate limit exceeded',
+        'rate_limit_exceeded',
+        ERROR_CODES.RATE_LIMIT_EXCEEDED,
+        { status, message: error.message },
+        ['Wait before retrying', 'Check GitHub rate limit status'],
+        true,
+        60
+      );
+    } else {
+      structuredError = createError(
+        `GitHub API error: ${error.message}`,
+        'github_api_error',
+        ERROR_CODES.GITHUB_API_ERROR,
+        { status, message: error.message },
+        ['Check GitHub API status', 'Verify API permissions'],
+        true,
+        10
+      );
+    }
+  } else {
+    // Generic error
+    structuredError = createError(
+      error.message || 'An unexpected error occurred',
+      'internal_error',
+      ERROR_CODES.INTERNAL_ERROR,
+      { stack: error.stack },
+      ['Check logs for more details', 'Report issue if problem persists'],
+      false
+    );
+  }
+
+  // Output error
+  if (output.isJsonMode()) {
+    console.error(JSON.stringify(structuredError, null, 2));
+  } else {
+    output.printError(structuredError.error);
+  }
+
+  // Set appropriate exit code
+  process.exit(structuredError.error.code);
+}
+
+/**
+ * Validate required arguments
+ * @param {Object} args - Arguments object
+ * @param {Array} required - Array of required argument names
+ * @param {Object} output - Output manager instance
+ */
+function validateRequiredArgs(args, required, output) {
+  const missing = required.filter(arg => !args[arg]);
+  
+  if (missing.length > 0) {
+    const error = createError(
+      `Missing required argument(s): ${missing.join(', ')}`,
+      'invalid_argument',
+      ERROR_CODES.INVALID_ARGUMENT,
+      { missing },
+      missing.map(arg => `Provide --${arg} or ${arg} parameter`),
+      false
+    );
+    
+    if (output.isJsonMode()) {
+      console.error(JSON.stringify(error, null, 2));
+    } else {
+      output.printError(error.error);
+    }
+    
+    process.exit(ERROR_CODES.INVALID_ARGUMENT);
+  }
+}
+
+/**
+ * Validate date parameters
+ * @param {string} month - Month parameter
+ * @param {string} year - Year parameter
+ * @param {Object} output - Output manager instance
+ */
+function validateDateParams(month, year, output) {
+  const monthNum = parseInt(month);
+  const yearNum = parseInt(year);
+  
+  if (isNaN(monthNum) || monthNum < 1 || monthNum > 12) {
+    const error = createError(
+      `Invalid month: ${month}. Must be 1-12.`,
+      'invalid_argument',
+      ERROR_CODES.INVALID_ARGUMENT,
+      { month },
+      ['Use month number 1-12'],
+      false
+    );
+    
+    if (output.isJsonMode()) {
+      console.error(JSON.stringify(error, null, 2));
+    } else {
+      output.printError(error.error);
+    }
+    
+    process.exit(ERROR_CODES.INVALID_ARGUMENT);
+  }
+  
+  if (isNaN(yearNum) || yearNum < 2000 || yearNum > 2100) {
+    const error = createError(
+      `Invalid year: ${year}. Must be 2000-2100.`,
+      'invalid_argument',
+      ERROR_CODES.INVALID_ARGUMENT,
+      { year },
+      ['Use 4-digit year format'],
+      false
+    );
+    
+    if (output.isJsonMode()) {
+      console.error(JSON.stringify(error, null, 2));
+    } else {
+      output.printError(error.error);
+    }
+    
+    process.exit(ERROR_CODES.INVALID_ARGUMENT);
+  }
+}
+
+/**
+ * Check if error is recoverable (should trigger retry logic)
+ * @param {Object} error - Error object
+ * @returns {boolean} True if error is recoverable
+ */
+function isRecoverableError(error) {
+  if (!error || !error.error) {
+    return false;
+  }
+  
+  const { code, recoverable } = error.error;
+  
+  // Explicitly recoverable
+  if (recoverable) {
+    return true;
+  }
+  
+  // Check error codes that are typically recoverable
+  const recoverableCodes = [
+    ERROR_CODES.GITHUB_API_ERROR,
+    ERROR_CODES.NETWORK_ERROR,
+    ERROR_CODES.TIMEOUT_ERROR,
+    ERROR_CODES.RATE_LIMIT_EXCEEDED,
+    ERROR_CODES.DATABASE_ERROR,
+  ];
+  
+  return recoverableCodes.includes(code);
+}
+
+/**
+ * Get retry delay in milliseconds for recoverable errors
+ * @param {Object} error - Error object
+ * @returns {number} Delay in milliseconds
+ */
+function getRetryDelay(error) {
+  if (!error || !error.error) {
+    return 5000; // Default 5 seconds
+  }
+  
+  const { retry_after, code } = error.error;
+  
+  if (retry_after) {
+    return retry_after * 1000; // Convert to milliseconds
+  }
+  
+  // Default delays based on error type
+  switch (code) {
+    case ERROR_CODES.RATE_LIMIT_EXCEEDED:
+      return 60000; // 1 minute
+    case ERROR_CODES.TIMEOUT_ERROR:
+      return 10000; // 10 seconds
+    case ERROR_CODES.NETWORK_ERROR:
+      return 5000; // 5 seconds
+    default:
+      return 5000; // 5 seconds
+  }
+}
+
+module.exports = {
+  ERROR_CODES,
+  createError,
+  handleCliError,
+  validateRequiredArgs,
+  validateDateParams,
+  isRecoverableError,
+  getRetryDelay,
+};

package/autochangelog-cli/src/cli/utils/logger.js

@@ -0,0 +1,75 @@
+const winston = require('winston');
+const chalk = require('chalk');
+
+/**
+ * Logger utility for CLI operations
+ * Provides structured logging with different levels and formats
+ */
+
+function setupLogger() {
+  // Determine log level from environment or default to info
+  const logLevel = process.env.LOG_LEVEL || 'info';
+  
+  // Check if output should be in JSON format (non-TTY or --json flag)
+  const isJsonOutput = process.env.FORCE_JSON === 'true' || 
+                      (!process.stdout.isTTY && process.env.FORCE_TEXT !== 'true');
+
+  // Define log format
+  const logFormat = isJsonOutput 
+    ? winston.format.json()
+    : winston.format.combine(
+        winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
+        winston.format.errors({ stack: true }),
+        winston.format.printf(({ timestamp, level, message, ...meta }) => {
+          let logMessage = `${timestamp} [${level.toUpperCase()}]: ${message}`;
+          
+          // Add metadata if present
+          if (Object.keys(meta).length > 0) {
+            logMessage += ` ${JSON.stringify(meta)}`;
+          }
+          
+          return logMessage;
+        })
+      );
+
+  // Create logger instance
+  const logger = winston.createLogger({
+    level: logLevel,
+    format: logFormat,
+    transports: [
+      new winston.transports.Console({
+        stderrLevels: ['error', 'warn'],
+        handleExceptions: true,
+        handleRejections: true,
+      }),
+    ],
+  });
+
+  // Add color support for human-readable output
+  if (!isJsonOutput) {
+    logger.format = winston.format.combine(
+      winston.format.colorize(),
+      logger.format
+    );
+  }
+
+  // Override console methods to use winston
+  const originalConsole = { ...console };
+  
+  console.log = (...args) => logger.info(args.join(' '));
+  console.error = (...args) => logger.error(args.join(' '));
+  console.warn = (...args) => logger.warn(args.join(' '));
+  console.info = (...args) => logger.info(args.join(' '));
+
+  // Restore original console for direct output
+  logger.restoreConsole = () => {
+    console.log = originalConsole.log;
+    console.error = originalConsole.error;
+    console.warn = originalConsole.warn;
+    console.info = originalConsole.info;
+  };
+
+  return logger;
+}
+
+module.exports = { setupLogger };