@tamyla/clodo-framework 1.0.0

package/dist/utils/dirname-helper.js

@@ -0,0 +1,35 @@
+/**
+ * Test-compatible __dirname utility
+ * Handles both ESM (import.meta.url) and CommonJS (__dirname) environments
+ */
+import { fileURLToPath } from 'url';
+import path from 'path';
+export function getDirname(importMetaUrl) {
+  // In test environment (CommonJS), use __dirname if available
+  if (typeof __dirname !== 'undefined') {
+    return __dirname;
+  }
+
+  // In ESM environment, use import.meta.url
+  if (importMetaUrl) {
+    const __filename = fileURLToPath(importMetaUrl);
+    return path.dirname(__filename);
+  }
+
+  // Fallback
+  return process.cwd();
+}
+export function getFilename(importMetaUrl) {
+  // In test environment (CommonJS), use __filename if available
+  if (typeof __filename !== 'undefined') {
+    return __filename;
+  }
+
+  // In ESM environment, use import.meta.url
+  if (importMetaUrl) {
+    return fileURLToPath(importMetaUrl);
+  }
+
+  // Fallback
+  return '';
+}

package/dist/utils/domain-config.js

@@ -0,0 +1,159 @@
+/**
+ * Domain Configuration Schema Utilities
+ * Provides schema creation and validation for domain configurations
+ */
+
+/**
+ * Create a domain configuration schema with validation rules
+ * @param {Object} options - Schema configuration options
+ * @returns {Object} Domain configuration schema
+ */
+export function createDomainConfigSchema(options = {}) {
+  const defaultSchema = {
+    type: 'object',
+    properties: {
+      domains: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              minLength: 1
+            },
+            domain: {
+              type: 'string',
+              pattern: '^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]*\\.[a-zA-Z]{2,}$'
+            },
+            accountId: {
+              type: 'string',
+              minLength: 1
+            },
+            zoneId: {
+              type: 'string',
+              minLength: 1
+            },
+            environment: {
+              type: 'string',
+              enum: ['development', 'staging', 'production']
+            },
+            ssl: {
+              type: 'boolean'
+            },
+            cors: {
+              type: 'boolean'
+            }
+          },
+          required: ['name', 'domain', 'environment'],
+          additionalProperties: false
+        },
+        minItems: 1
+      }
+    },
+    required: ['domains'],
+    additionalProperties: false,
+    ...options
+  };
+  return {
+    schema: defaultSchema,
+    validate: function (data) {
+      const errors = [];
+      if (!data || typeof data !== 'object') {
+        errors.push({
+          field: 'root',
+          message: 'Data must be an object'
+        });
+        return {
+          valid: false,
+          errors
+        };
+      }
+      if (!Array.isArray(data.domains)) {
+        errors.push({
+          field: 'domains',
+          message: 'Domains must be an array'
+        });
+        return {
+          valid: false,
+          errors
+        };
+      }
+      if (data.domains.length === 0) {
+        errors.push({
+          field: 'domains',
+          message: 'At least one domain is required'
+        });
+        return {
+          valid: false,
+          errors
+        };
+      }
+      data.domains.forEach((domain, index) => {
+        if (!domain.name) {
+          errors.push({
+            field: `domains[${index}].name`,
+            message: 'Domain name is required'
+          });
+        }
+        if (!domain.domain) {
+          errors.push({
+            field: `domains[${index}].domain`,
+            message: 'Domain URL is required'
+          });
+        } else if (!/^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]*\.[a-zA-Z]{2,}$/.test(domain.domain)) {
+          errors.push({
+            field: `domains[${index}].domain`,
+            message: 'Invalid domain format'
+          });
+        }
+        if (!domain.environment) {
+          errors.push({
+            field: `domains[${index}].environment`,
+            message: 'Environment is required'
+          });
+        } else if (!['development', 'staging', 'production'].includes(domain.environment)) {
+          errors.push({
+            field: `domains[${index}].environment`,
+            message: 'Environment must be development, staging, or production'
+          });
+        }
+      });
+      return {
+        valid: errors.length === 0,
+        errors
+      };
+    }
+  };
+}
+
+/**
+ * Validate domain configuration data
+ * @param {Object} data - Domain configuration data to validate
+ * @param {Object} schema - Optional custom schema
+ * @returns {Object} Validation result
+ */
+export function validateDomainConfig(data, schema = null) {
+  const configSchema = schema || createDomainConfigSchema();
+  return configSchema.validate(data);
+}
+
+/**
+ * Create a default domain configuration
+ * @param {string} serviceName - Name of the service
+ * @param {string} domainName - Primary domain name
+ * @param {string} environment - Target environment
+ * @returns {Object} Default domain configuration
+ */
+export function createDefaultDomainConfig(serviceName, domainName, environment = 'development') {
+  return {
+    domains: [{
+      name: serviceName,
+      domain: domainName,
+      accountId: 'your-account-id',
+      zoneId: 'your-zone-id',
+      environment,
+      ssl: true,
+      cors: environment !== 'production'
+    }]
+  };
+}

package/dist/utils/error-recovery.js

@@ -0,0 +1,240 @@
+/**
+ * Error Recovery Module
+ * Implements circuit breakers, retries, and graceful degradation
+ */
+
+export class ErrorRecoveryManager {
+  constructor(options = {}) {
+    this.options = options;
+    this.config = null;
+    this.circuitStates = new Map(); // service -> { failures, lastFailure, state }
+    this.retryStates = new Map(); // operation -> retry count
+  }
+
+  /**
+   * Initialize with framework configuration
+   */
+  async initialize() {
+    // Import framework config for consistent timing and retry settings
+    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
+    };
+  }
+
+  /**
+   * Execute operation with error recovery
+   */
+  async executeWithRecovery(operation, options = {}) {
+    const config = {
+      ...this.config,
+      ...options
+    };
+    const operationId = this.getOperationId(operation);
+
+    // Check circuit breaker
+    if (this.isCircuitOpen(operationId)) {
+      if (config.gracefulDegradation) {
+        return this.executeGracefulFallback(operation, config);
+      }
+      throw new Error(`Circuit breaker open for operation: ${operationId}`);
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+      try {
+        const result = await operation();
+        this.recordSuccess(operationId);
+        return result;
+      } catch (error) {
+        lastError = error;
+        this.recordFailure(operationId, error);
+        if (attempt < config.maxRetries) {
+          const delay = this.calculateRetryDelay(attempt, config.retryDelay);
+          await this.delay(delay);
+        }
+      }
+    }
+
+    // All retries exhausted
+    if (config.gracefulDegradation) {
+      return this.executeGracefulFallback(operation, config);
+    }
+    throw lastError;
+  }
+
+  /**
+   * Check if circuit breaker is open
+   */
+  isCircuitOpen(operationId) {
+    const state = this.circuitStates.get(operationId);
+    if (!state) return false;
+    if (state.state === 'open') {
+      // Check if timeout has passed
+      if (Date.now() - state.lastFailure > this.config.circuitBreakerTimeout) {
+        state.state = 'half-open';
+        state.failures = 0;
+        return false;
+      }
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Record operation success
+   */
+  recordSuccess(operationId) {
+    const state = this.circuitStates.get(operationId);
+    if (state) {
+      if (state.state === 'half-open') {
+        state.state = 'closed';
+        state.failures = 0;
+      }
+    }
+  }
+
+  /**
+   * Record operation failure
+   */
+  recordFailure(operationId, error) {
+    let state = this.circuitStates.get(operationId);
+    if (!state) {
+      state = {
+        failures: 0,
+        lastFailure: 0,
+        state: 'closed'
+      };
+      this.circuitStates.set(operationId, state);
+    }
+    state.failures++;
+    state.lastFailure = Date.now();
+    if (state.failures >= this.config.circuitBreakerThreshold) {
+      state.state = 'open';
+    }
+  }
+
+  /**
+   * Calculate retry delay with exponential backoff
+   */
+  calculateRetryDelay(attempt, baseDelay) {
+    const exponentialDelay = baseDelay * Math.pow(2, attempt);
+    const jitter = Math.random() * 0.1 * exponentialDelay;
+    return Math.min(exponentialDelay + jitter, 30000); // Max 30 seconds
+  }
+
+  /**
+   * Execute graceful fallback
+   */
+  async executeGracefulFallback(operation, config) {
+    console.warn(`Executing graceful fallback for operation`);
+
+    // Try to execute with reduced functionality
+    try {
+      // For deployment operations, try a simplified version
+      if (operation.name && operation.name.includes('deploy')) {
+        return {
+          success: false,
+          degraded: true,
+          message: 'Operation executed in degraded mode'
+        };
+      }
+
+      // For data operations, return cached or default data
+      if (operation.name && operation.name.includes('fetch')) {
+        return {
+          data: [],
+          cached: true,
+          degraded: true
+        };
+      }
+
+      // Default fallback
+      return {
+        success: false,
+        degraded: true,
+        fallback: true
+      };
+    } catch (fallbackError) {
+      console.error('Graceful fallback also failed:', fallbackError);
+      throw fallbackError;
+    }
+  }
+
+  /**
+   * Get unique operation ID
+   */
+  getOperationId(operation) {
+    if (typeof operation === 'function' && operation.name) {
+      return operation.name;
+    }
+    return `operation_${Date.now()}_${Math.random()}`;
+  }
+
+  /**
+   * Utility delay function
+   */
+  delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Get circuit breaker status
+   */
+  getCircuitStatus(operationId) {
+    const state = this.circuitStates.get(operationId);
+    if (!state) {
+      return {
+        state: 'closed',
+        failures: 0
+      };
+    }
+    return {
+      state: state.state,
+      failures: state.failures,
+      lastFailure: state.lastFailure,
+      timeSinceLastFailure: Date.now() - state.lastFailure
+    };
+  }
+
+  /**
+   * Reset circuit breaker
+   */
+  resetCircuit(operationId) {
+    this.circuitStates.delete(operationId);
+  }
+
+  /**
+   * Get all circuit statuses
+   */
+  getAllCircuitStatuses() {
+    const statuses = {};
+    for (const [operationId, state] of this.circuitStates) {
+      statuses[operationId] = this.getCircuitStatus(operationId);
+    }
+    return statuses;
+  }
+}
+
+/**
+ * Retry wrapper for functions
+ */
+export function withRetry(fn, options = {}) {
+  const recovery = new ErrorRecoveryManager(options);
+  return (...args) => recovery.executeWithRecovery(() => fn(...args), options);
+}
+
+/**
+ * Circuit breaker wrapper for functions
+ */
+export function withCircuitBreaker(fn, options = {}) {
+  const recovery = new ErrorRecoveryManager(options);
+  return (...args) => recovery.executeWithRecovery(() => fn(...args), options);
+}

package/dist/utils/esm-helper.js

@@ -0,0 +1,52 @@
+/**
+ * ESM Helper - Provides __dirname and __filename for ES modules
+ * Handles both normal ESM environment and test environment transformation
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+/**
+ * Get __filename and __dirname for current module
+ * @param {string} importMetaUrl - import.meta.url from calling module
+ * @param {string} fallbackPath - fallback path relative to project root for tests
+ * @returns {Object} - {__filename, __dirname}
+ */
+export function getFileInfo(importMetaUrl, fallbackPath) {
+  try {
+    const __filename = fileURLToPath(importMetaUrl);
+    const __dirname = dirname(__filename);
+    return {
+      __filename,
+      __dirname
+    };
+  } catch (error) {
+    // Fallback for test environment where import.meta is transformed
+    const __dirname = join(process.cwd(), fallbackPath);
+    const __filename = join(__dirname, 'index.js'); // Generic filename
+    return {
+      __filename,
+      __dirname
+    };
+  }
+}
+
+/**
+ * Get just __dirname for current module
+ * @param {string} importMetaUrl - import.meta.url from calling module
+ * @param {string} fallbackPath - fallback path relative to project root for tests
+ * @returns {string} - __dirname
+ */
+export function getDirname(importMetaUrl, fallbackPath) {
+  return getFileInfo(importMetaUrl, fallbackPath).__dirname;
+}
+
+/**
+ * Get just __filename for current module
+ * @param {string} importMetaUrl - import.meta.url from calling module
+ * @param {string} fallbackPath - fallback path relative to project root for tests
+ * @returns {string} - __filename
+ */
+export function getFilename(importMetaUrl, fallbackPath) {
+  return getFileInfo(importMetaUrl, fallbackPath).__filename;
+}