@tamyla/clodo-framework 3.1.4 → 3.1.8

package/bin/shared/utils/error-recovery.js

@@ -1,6 +1,14 @@
 /**
- * Error Recovery Module
+ * Error Recovery Module - UNIFIED
  * Implements circuit breakers, retries, and graceful degradation
+ * 
+ * Consolidation: Oct 26, 2025 - Phase 3.2.3a
+ * 
+ * Merged from:
+ * - src/utils/error-recovery.js (225 lines)
+ * - bin/shared/utils/error-recovery.js (225 lines - DUPLICATE)
+ * 
+ * This is the canonical version. All imports should use this version.
  */
 
 export class ErrorRecoveryManager {
@@ -16,17 +24,29 @@ export class ErrorRecoveryManager {
    */
   async initialize() {
     // Import framework config for consistent timing and retry settings
-    const { frameworkConfig } = await import('../../../dist/utils/framework-config.js');
-    const timing = frameworkConfig.getTiming();
-    
-    this.config = {
-      maxRetries: this.options.maxRetries || timing.retryAttempts,
-      retryDelay: this.options.retryDelay || timing.retryDelay,
-      circuitBreakerThreshold: this.options.circuitBreakerThreshold || timing.circuitBreakerThreshold,
-      circuitBreakerTimeout: this.options.circuitBreakerTimeout || timing.circuitBreakerTimeout,
-      gracefulDegradation: this.options.gracefulDegradation !== false,
-      ...this.options
-    };
+    try {
+      const { frameworkConfig } = await import('./framework-config.js');
+      const timing = frameworkConfig.getTiming();
+      
+      this.config = {
+        maxRetries: this.options.maxRetries || timing.retryAttempts,
+        retryDelay: this.options.retryDelay || timing.retryDelay,
+        circuitBreakerThreshold: this.options.circuitBreakerThreshold || timing.circuitBreakerThreshold,
+        circuitBreakerTimeout: this.options.circuitBreakerTimeout || timing.circuitBreakerTimeout,
+        gracefulDegradation: this.options.gracefulDegradation !== false,
+        ...this.options
+      };
+    } catch (error) {
+      // Fallback to defaults if framework config not available
+      this.config = {
+        maxRetries: this.options.maxRetries || 3,
+        retryDelay: this.options.retryDelay || 1000,
+        circuitBreakerThreshold: this.options.circuitBreakerThreshold || 5,
+        circuitBreakerTimeout: this.options.circuitBreakerTimeout || 60000,
+        gracefulDegradation: this.options.gracefulDegradation !== false,
+        ...this.options
+      };
+    }
   }
 
   /**
@@ -222,4 +242,4 @@ export function withRetry(fn, options = {}) {
 export function withCircuitBreaker(fn, options = {}) {
   const recovery = new ErrorRecoveryManager(options);
   return (...args) => recovery.executeWithRecovery(() => fn(...args), options);
-}
+}

package/bin/shared/utils/file-manager.js

@@ -0,0 +1,162 @@
+/**
+ * Centralized File Manager
+ * Replaces: 12 scattered file operation implementations
+ * Savings: 200+ lines
+ */
+
+import { 
+  readFileSync, writeFileSync, appendFileSync,
+  existsSync, mkdirSync, statSync
+} from 'fs';
+import { dirname, basename } from 'path';
+
+export class FileManager {
+  constructor(options = {}) {
+    this.cache = new Map();
+    this.enableCache = options.enableCache !== false;
+    this.createBackups = options.createBackups !== false;
+    this.backupDir = options.backupDir || '.backups';
+  }
+
+  /**
+   * Read JSON configuration file
+   */
+  readConfig(path, defaultValue = null) {
+    try {
+      if (this.enableCache && this.cache.has(path)) {
+        return this.cache.get(path);
+      }
+      
+      if (!existsSync(path)) {
+        if (defaultValue !== null) return defaultValue;
+        throw new Error(`Configuration file not found: ${path}`);
+      }
+      
+      const content = readFileSync(path, 'utf8');
+      const data = JSON.parse(content);
+      
+      if (this.enableCache) {
+        this.cache.set(path, data);
+      }
+      
+      return data;
+    } catch (error) {
+      if (error.message.includes('JSON')) {
+        throw new Error(`Invalid JSON in configuration file: ${error.message}`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Write JSON configuration file with optional backup
+   */
+  writeConfig(path, data, options = {}) {
+    try {
+      // Create backup if needed
+      if (this.createBackups && existsSync(path)) {
+        this.createBackup(path);
+      }
+      
+      // Ensure directory exists
+      this.ensureDir(dirname(path));
+      
+      // Write file
+      const content = JSON.stringify(data, null, 2);
+      writeFileSync(path, content, 'utf8');
+      
+      // Clear cache
+      if (this.enableCache) {
+        this.cache.delete(path);
+      }
+      
+      return { success: true, path };
+    } catch (error) {
+      throw new Error(`Failed to write configuration: ${error.message}`);
+    }
+  }
+
+  /**
+   * Read text file
+   */
+  readFile(path) {
+    if (!existsSync(path)) {
+      throw new Error(`File not found: ${path}`);
+    }
+    return readFileSync(path, 'utf8');
+  }
+
+  /**
+   * Write text file
+   */
+  writeFile(path, content) {
+    this.ensureDir(dirname(path));
+    writeFileSync(path, content, 'utf8');
+  }
+
+  /**
+   * Append to file
+   */
+  appendFile(path, content) {
+    this.ensureDir(dirname(path));
+    appendFileSync(path, content, 'utf8');
+  }
+
+  /**
+   * Check if file exists
+   */
+  exists(path) {
+    return existsSync(path);
+  }
+
+  /**
+   * Ensure directory exists
+   */
+  ensureDir(dir) {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * Create backup of file
+   */
+  createBackup(path) {
+    this.ensureDir(this.backupDir);
+    
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const fileName = basename(path);
+    const backupPath = `${this.backupDir}/${fileName}.${timestamp}.bak`;
+    
+    const content = readFileSync(path, 'utf8');
+    writeFileSync(backupPath, content, 'utf8');
+    
+    return backupPath;
+  }
+
+  /**
+   * Get file stats
+   */
+  getStats(path) {
+    if (!existsSync(path)) {
+      return null;
+    }
+    return statSync(path);
+  }
+
+  /**
+   * Clear cache
+   */
+  clearCache(path = null) {
+    if (path) {
+      this.cache.delete(path);
+    } else {
+      this.cache.clear();
+    }
+  }
+}
+
+/**
+ * Export singleton instance
+ */
+export const fileManager = new FileManager();

package/bin/shared/utils/formatters.js

@@ -0,0 +1,247 @@
+/**
+ * Data Formatters for Clodo Framework
+ * Centralizes all data transformation logic
+ * Replaces: 5 scattered formatting implementations
+ * Savings: 150+ lines
+ */
+
+/**
+ * Name formatting utilities
+ */
+export const NameFormatters = {
+  /**
+   * Convert kebab-case to Display Case
+   * Example: 'my-service' → 'My Service'
+   */
+  toDisplayName(kebabCase) {
+    if (!kebabCase) return '';
+    return kebabCase
+      .replace(/-/g, ' ')
+      .replace(/\b\w/g, l => l.toUpperCase());
+  },
+
+  /**
+   * Convert camelCase to kebab-case
+   * Example: 'myService' → 'my-service'
+   */
+  toKebabCase(camelCase) {
+    if (!camelCase) return '';
+    return camelCase
+      .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+      .replace(/^([A-Z])([A-Z])/g, '$1-$2')
+      .toLowerCase();
+  },
+
+  /**
+   * Convert kebab-case to camelCase
+   * Example: 'my-service' → 'myService'
+   */
+  toCamelCase(kebabCase) {
+    if (!kebabCase) return '';
+    return kebabCase
+      .split('-')
+      .map((part, i) => 
+        i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)
+      )
+      .join('');
+  },
+
+  /**
+   * Convert snake_case to camelCase
+   * Example: 'my_service' → 'myService'
+   */
+  snakeToCamel(snakeCase) {
+    if (!snakeCase) return '';
+    return snakeCase
+      .split('_')
+      .map((part, i) => 
+        i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)
+      )
+      .join('');
+  }
+};
+
+/**
+ * URL formatting utilities
+ */
+export const UrlFormatters = {
+  /**
+   * Build service URL
+   * Example: buildServiceUrl('api', 'example.com', 'production')
+   * → 'https://api.example.com'
+   */
+  buildServiceUrl(serviceName, domain, environment = 'production') {
+    if (!serviceName || !domain) return '';
+    
+    const prefix = environment === 'production' 
+      ? serviceName 
+      : `${serviceName}-${environment.substring(0, 3)}`;
+    
+    return `https://${prefix}.${domain}`;
+  },
+
+  /**
+   * Build production URL
+   */
+  buildProductionUrl(serviceName, domain) {
+    return this.buildServiceUrl(serviceName, domain, 'production');
+  },
+
+  /**
+   * Build staging URL
+   */
+  buildStagingUrl(serviceName, domain) {
+    return this.buildServiceUrl(serviceName, domain, 'staging');
+  },
+
+  /**
+   * Build development URL
+   */
+  buildDevUrl(serviceName, domain) {
+    return this.buildServiceUrl(serviceName, domain, 'development');
+  },
+
+  /**
+   * Build API endpoint URL
+   */
+  buildApiUrl(serviceName, domain, path = '') {
+    const baseUrl = this.buildProductionUrl(serviceName, domain);
+    return path ? `${baseUrl}${path}` : baseUrl;
+  }
+};
+
+/**
+ * Resource name formatters
+ */
+export const ResourceFormatters = {
+  /**
+   * Format database name
+   * Example: 'my-service' → 'my-service-db'
+   */
+  databaseName(serviceName) {
+    if (!serviceName) return '';
+    return `${serviceName}-db`;
+  },
+
+  /**
+   * Format worker name
+   * Example: 'my-service' → 'my-service-worker'
+   */
+  workerName(serviceName) {
+    if (!serviceName) return '';
+    return `${serviceName}-worker`;
+  },
+
+  /**
+   * Format service directory
+   * Example: 'my-service' → './services/my-service'
+   */
+  serviceDirectory(serviceName) {
+    if (!serviceName) return '';
+    return `./services/${serviceName}`;
+  },
+
+  /**
+   * Format configuration key
+   * Example: 'cloudflareApiToken' → 'cloudflare-api-token'
+   */
+  configKey(camelCase) {
+    return NameFormatters.toKebabCase(camelCase);
+  }
+};
+
+/**
+ * Environment-related formatters
+ */
+export const EnvironmentFormatters = {
+  /**
+   * Get environment variable prefix
+   * Example: 'production' → 'PROD_'
+   */
+  getEnvPrefix(environment) {
+    switch (environment) {
+      case 'production':
+        return 'PROD_';
+      case 'staging':
+        return 'STAGING_';
+      case 'development':
+        return 'DEV_';
+      default:
+        return 'APP_';
+    }
+  },
+
+  /**
+   * Get log level for environment
+   * Example: 'production' → 'warn'
+   */
+  getLogLevel(environment) {
+    switch (environment) {
+      case 'production':
+        return 'warn';
+      case 'staging':
+        return 'info';
+      case 'development':
+        return 'debug';
+      default:
+        return 'info';
+    }
+  },
+
+  /**
+   * Get CORS policy for environment
+   */
+  getCorsPolicy(domain, environment) {
+    switch (environment) {
+      case 'production':
+        return `https://${domain}`;
+      case 'staging':
+        return `https://${domain}`;
+      case 'development':
+        return '*'; // Allow all in development
+      default:
+        return '*';
+    }
+  }
+};
+
+/**
+ * Version formatting
+ */
+export const VersionFormatters = {
+  /**
+   * Normalize version string
+   */
+  normalize(version) {
+    const match = version.match(/(\d+\.\d+\.\d+)/);
+    return match ? match[1] : '1.0.0';
+  },
+
+  /**
+   * Bump version
+   */
+  bump(version, type = 'patch') {
+    const [major, minor, patch] = version.split('.').map(Number);
+    
+    switch (type) {
+      case 'major':
+        return `${major + 1}.0.0`;
+      case 'minor':
+        return `${major}.${minor + 1}.0`;
+      case 'patch':
+      default:
+        return `${major}.${minor}.${patch + 1}`;
+    }
+  }
+};
+
+/**
+ * Convenience exports - combine all formatters
+ */
+export const Formatters = {
+  ...NameFormatters,
+  ...UrlFormatters,
+  ...ResourceFormatters,
+  ...EnvironmentFormatters,
+  ...VersionFormatters
+};

package/bin/shared/utils/index.js

@@ -3,7 +3,17 @@
  * Exports all general utility functions and managers
  */
 
-export { InteractivePrompts } from './interactive-prompts.js';
-export { ErrorRecovery } from './error-recovery.js';
-export { GracefulShutdownManager } from './graceful-shutdown-manager.js';
-export { RateLimiter } from './rate-limiter.js';
+// Interactive prompts utilities
+export { askUser, askYesNo, askChoice, askMultiChoice, closePrompts, showProgress, askPassword } from './interactive-prompts.js';
+
+// Error recovery and handling
+export { ErrorRecoveryManager, withRetry, withCircuitBreaker } from './error-recovery.js';
+
+// Graceful shutdown
+export { GracefulShutdownManager, getShutdownManager, initializeGracefulShutdown, withGracefulShutdown } from './graceful-shutdown-manager.js';
+
+// Rate limiting
+export { executeWithRateLimit, queueRequest, getRateLimitStatus, clearQueues, RATE_LIMITS } from './rate-limiter.js';
+
+// Unified error handling module (Phase 3.2.3d - consolidated from 5 sources)
+export { default as ErrorHandler, createErrorResponse, createContextualError, createErrorHandler } from './ErrorHandler.js';

package/bin/shared/validation/ValidationRegistry.js

@@ -0,0 +1,143 @@
+/**
+ * Unified Validation Registry
+ * Centralizes all validation logic
+ * Replaces: Fragmented validation across 3+ files
+ * Savings: 100+ lines
+ */
+
+/**
+ * Import validators from src/utils (source of truth)
+ */
+import {
+  validateServiceName,
+  validateDomainName,
+  validateCloudflareToken,
+  validateCloudflareId,
+  validateServiceType,
+  validateEnvironment
+} from '../../../src/utils/validation.js';
+
+/**
+ * Validation Registry - Single source of truth for all validators
+ */
+export class ValidationRegistry {
+  /**
+   * Standard validation rules
+   */
+  static RULES = {
+    // Service configuration
+    serviceName: {
+      validator: validateServiceName,
+      message: 'Service name must be 3-50 characters, lowercase with hyphens only'
+    },
+    
+    domainName: {
+      validator: validateDomainName,
+      message: 'Domain name must be valid (e.g., example.com)'
+    },
+    
+    serviceType: {
+      validator: validateServiceType,
+      message: 'Service type must be one of: data-service, auth-service, content-service, api-gateway, generic'
+    },
+    
+    environment: {
+      validator: validateEnvironment,
+      message: 'Environment must be one of: development, staging, production'
+    },
+    
+    // Cloudflare configuration
+    cloudflareToken: {
+      validator: validateCloudflareToken,
+      message: 'Cloudflare API token must be at least 20 characters'
+    },
+    
+    cloudflareAccountId: {
+      validator: validateCloudflareId,
+      message: 'Cloudflare Account ID must be 32 hexadecimal characters'
+    },
+    
+    cloudflareZoneId: {
+      validator: validateCloudflareId,
+      message: 'Cloudflare Zone ID must be 32 hexadecimal characters'
+    }
+  };
+
+  /**
+   * Validate a value against a registered rule
+   * Returns: { valid: boolean, message: string }
+   */
+  static validate(ruleName, value) {
+    const rule = this.RULES[ruleName];
+    
+    if (!rule) {
+      return {
+        valid: false,
+        message: `Unknown validation rule: ${ruleName}`
+      };
+    }
+    
+    try {
+      const isValid = rule.validator(value);
+      return {
+        valid: isValid,
+        message: isValid ? 'Valid' : rule.message
+      };
+    } catch (error) {
+      return {
+        valid: false,
+        message: `Validation error: ${error.message}`
+      };
+    }
+  }
+
+  /**
+   * Validate multiple fields
+   * Returns: { valid: boolean, errors: Map<fieldName, message> }
+   */
+  static validateMultiple(fields) {
+    const errors = new Map();
+    
+    for (const [fieldName, value] of Object.entries(fields)) {
+      const result = this.validate(fieldName, value);
+      if (!result.valid) {
+        errors.set(fieldName, result.message);
+      }
+    }
+    
+    return {
+      valid: errors.size === 0,
+      errors
+    };
+  }
+
+  /**
+   * Register custom validation rule
+   * Usage: ValidationRegistry.register('customRule', customValidator, 'Custom error message')
+   */
+  static register(ruleName, validator, message = 'Invalid value') {
+    this.RULES[ruleName] = {
+      validator,
+      message
+    };
+  }
+
+  /**
+   * Get all registered rules
+   */
+  static getAllRules() {
+    return Object.keys(this.RULES);
+  }
+
+  /**
+   * Get rule details
+   */
+  static getRule(ruleName) {
+    return this.RULES[ruleName];
+  }
+}
+
+/**
+ * Export for convenience
+ */
+export const validators = ValidationRegistry;