@tamyla/clodo-framework 1.0.0

package/dist/worker/index.js

@@ -0,0 +1,4 @@
+// Worker Integration Framework
+// Helpers for Cloudflare Worker integration
+
+export * from './integration.js';

package/dist/worker/integration.js

@@ -0,0 +1,332 @@
+import { featureManager, COMMON_FEATURES } from '../config/features.js';
+import { getDomainFromEnv, createEnvironmentConfig } from '../config/domains.js';
+import { createLogger } from '../utils/index.js';
+const logger = createLogger('WorkerIntegration');
+
+/**
+ * Initializes a service with domain and feature context
+ * @param {Object} env - Cloudflare Worker environment
+ * @param {Object} domainConfigs - Available domain configurations
+ * @returns {Object} Service initialization context
+ */
+export const initializeService = (env, domainConfigs = {}) => {
+  try {
+    // Get domain configuration from environment
+    const domainConfig = getDomainFromEnv(env, domainConfigs);
+    if (!domainConfig) {
+      throw new Error('No domain configuration found for service initialization');
+    }
+
+    // Set domain in feature manager
+    featureManager.setDomain(domainConfig);
+
+    // Create environment-specific config
+    const environment = env.ENVIRONMENT || env.NODE_ENV || 'development';
+    const envConfig = createEnvironmentConfig(domainConfig, environment);
+
+    // Initialize service context
+    const serviceContext = {
+      domain: domainConfig.name,
+      environment,
+      features: featureManager.getEnabledFeatures(),
+      config: envConfig,
+      env,
+      isProduction: environment === 'production',
+      isStaging: environment === 'staging',
+      isDevelopment: environment === 'development'
+    };
+    logger.info(`Service initialized: ${domainConfig.name} (${environment})`);
+    logger.debug(`Enabled features: ${serviceContext.features.join(', ')}`);
+    return serviceContext;
+  } catch (error) {
+    logger.error(`Service initialization failed: ${error.message}`);
+    throw error;
+  }
+};
+
+/**
+ * Creates a feature guard middleware for Cloudflare Workers
+ * @param {string} featureName - Name of the feature to guard
+ * @param {Object} options - Guard options
+ * @returns {Function} Feature guard middleware
+ */
+export const createFeatureGuard = (featureName, options = {}) => {
+  const {
+    fallbackResponse = null,
+    required = true,
+    logAccess = true
+  } = options;
+  return handler => {
+    return async (request, env, ctx) => {
+      const isEnabled = featureManager.isEnabled(featureName);
+      if (logAccess) {
+        logger.debug(`Feature access: ${featureName} = ${isEnabled}`);
+      }
+      if (required && !isEnabled) {
+        const response = fallbackResponse || new Response(JSON.stringify({
+          error: 'Feature not available',
+          feature: featureName,
+          message: `The ${featureName} feature is not enabled for this domain`
+        }), {
+          status: 404,
+          headers: {
+            'Content-Type': 'application/json'
+          }
+        });
+        logger.warn(`Feature guard blocked access to ${featureName}`);
+        return response;
+      }
+      if (!isEnabled) {
+        logger.info(`Feature ${featureName} disabled, skipping handler`);
+        return fallbackResponse || new Response('Not Found', {
+          status: 404
+        });
+      }
+
+      // Feature is enabled, proceed with handler
+      return handler(request, env, ctx);
+    };
+  };
+};
+
+/**
+ * Creates a route-based feature guard
+ * @param {Object} routeConfig - Route configuration with feature requirements
+ * @returns {Function} Route guard middleware
+ */
+export const createRouteGuard = routeConfig => {
+  return handler => {
+    return async (request, env, ctx) => {
+      // Check route-specific feature requirements
+      for (const [feature, required] of Object.entries(routeConfig)) {
+        if (required && !featureManager.isEnabled(feature)) {
+          logger.warn(`Route blocked: missing required feature ${feature}`);
+          return new Response(JSON.stringify({
+            error: 'Feature required',
+            feature,
+            message: `This endpoint requires the ${feature} feature`
+          }), {
+            status: 403,
+            headers: {
+              'Content-Type': 'application/json'
+            }
+          });
+        }
+      }
+      return handler(request, env, ctx);
+    };
+  };
+};
+
+/**
+ * Creates an environment-based guard
+ * @param {string[]} allowedEnvironments - Array of allowed environments
+ * @returns {Function} Environment guard middleware
+ */
+export const createEnvironmentGuard = (allowedEnvironments = ['production', 'staging']) => {
+  return handler => {
+    return async (request, env, ctx) => {
+      const currentEnv = env.ENVIRONMENT || env.NODE_ENV || 'development';
+      if (!allowedEnvironments.includes(currentEnv)) {
+        logger.warn(`Environment guard blocked: ${currentEnv} not in ${allowedEnvironments.join(', ')}`);
+        return new Response('Not Found', {
+          status: 404
+        });
+      }
+      return handler(request, env, ctx);
+    };
+  };
+};
+
+/**
+ * Creates a rate limiting guard (basic implementation)
+ * @param {Object} options - Rate limiting options
+ * @returns {Function} Rate limiting middleware
+ */
+export const createRateLimitGuard = (options = {}) => {
+  const {
+    windowMs = 60000,
+    // 1 minute
+    maxRequests = 100,
+    skipSuccessfulRequests = false,
+    skipFailedRequests = false
+  } = options;
+  const requests = new Map();
+  const cleanup = () => {
+    const now = Date.now();
+    for (const [key, data] of requests.entries()) {
+      if (now - data.resetTime > windowMs) {
+        requests.delete(key);
+      }
+    }
+  };
+  return handler => {
+    return async (request, env, ctx) => {
+      // Skip rate limiting if feature is disabled
+      if (!featureManager.isEnabled(COMMON_FEATURES.RATE_LIMITING)) {
+        return handler(request, env, ctx);
+      }
+      const clientId = request.headers.get('CF-Connecting-IP') || 'anonymous';
+      const now = Date.now();
+      cleanup();
+      const clientData = requests.get(clientId) || {
+        count: 0,
+        resetTime: now + windowMs
+      };
+
+      // Reset counter if window has passed
+      if (now > clientData.resetTime) {
+        clientData.count = 0;
+        clientData.resetTime = now + windowMs;
+      }
+      clientData.count++;
+      requests.set(clientId, clientData);
+
+      // Check if limit exceeded
+      if (clientData.count > maxRequests) {
+        logger.warn(`Rate limit exceeded for ${clientId}`);
+        return new Response(JSON.stringify({
+          error: 'Too many requests',
+          retryAfter: Math.ceil((clientData.resetTime - now) / 1000)
+        }), {
+          status: 429,
+          headers: {
+            'Content-Type': 'application/json',
+            'Retry-After': Math.ceil((clientData.resetTime - now) / 1000).toString()
+          }
+        });
+      }
+      const response = await handler(request, env, ctx);
+
+      // Optionally skip successful/failed requests from count
+      if (skipSuccessfulRequests && response.ok || skipFailedRequests && !response.ok) {
+        clientData.count--;
+        requests.set(clientId, clientData);
+      }
+      return response;
+    };
+  };
+};
+
+/**
+ * Creates CORS middleware
+ * @param {Object} options - CORS options
+ * @returns {Function} CORS middleware
+ */
+export const createCorsMiddleware = (options = {}) => {
+  const {
+    origins = ['*'],
+    methods = ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+    headers = ['Content-Type', 'Authorization'],
+    credentials = false,
+    maxAge = 86400
+  } = options;
+  return handler => {
+    return async (request, env, ctx) => {
+      // Handle preflight requests
+      if (request.method === 'OPTIONS') {
+        const origin = request.headers.get('Origin');
+
+        // Check if origin is allowed
+        const isWildcard = origins.includes('*');
+        const isOriginAllowed = isWildcard || origin && origins.includes(origin);
+        if (!isOriginAllowed) {
+          return new Response('CORS policy violation: Origin not allowed', {
+            status: 403,
+            headers: {
+              'Content-Type': 'text/plain'
+            }
+          });
+        }
+        const allowedOrigin = isWildcard ? '*' : origin;
+        return new Response(null, {
+          status: 200,
+          headers: {
+            'Access-Control-Allow-Origin': allowedOrigin,
+            'Access-Control-Allow-Methods': methods.join(', '),
+            'Access-Control-Allow-Headers': headers.join(', '),
+            'Access-Control-Max-Age': maxAge.toString(),
+            ...(credentials && {
+              'Access-Control-Allow-Credentials': 'true'
+            })
+          }
+        });
+      }
+
+      // Handle actual requests
+      const response = await handler(request, env, ctx);
+      const origin = request.headers.get('Origin');
+
+      // Add CORS headers to response only if origin is allowed
+      const isWildcard = origins.includes('*');
+      const isOriginAllowed = isWildcard || origin && origins.includes(origin);
+      if (isOriginAllowed) {
+        const allowedOrigin = isWildcard ? '*' : origin;
+        response.headers.set('Access-Control-Allow-Origin', allowedOrigin);
+        response.headers.set('Access-Control-Allow-Methods', methods.join(', '));
+        response.headers.set('Access-Control-Allow-Headers', headers.join(', '));
+        if (credentials) {
+          response.headers.set('Access-Control-Allow-Credentials', 'true');
+        }
+      }
+      return response;
+    };
+  };
+};
+
+/**
+ * Creates error handling middleware
+ * @param {Object} options - Error handling options
+ * @returns {Function} Error handling middleware
+ */
+export const createErrorHandler = (options = {}) => {
+  const {
+    includeStack = false,
+    logErrors = true,
+    transformError = null
+  } = options;
+  return handler => {
+    return async (request, env, ctx) => {
+      try {
+        return await handler(request, env, ctx);
+      } catch (error) {
+        if (logErrors) {
+          logger.error(`Request error: ${error.message}`, {
+            url: request.url,
+            method: request.method,
+            stack: includeStack ? error.stack : undefined
+          });
+        }
+
+        // Transform error if transformer provided
+        let errorResponse = {
+          error: 'Internal Server Error',
+          message: error.message,
+          ...(includeStack && {
+            stack: error.stack
+          })
+        };
+        if (transformError) {
+          errorResponse = transformError(error, errorResponse);
+        }
+        return new Response(JSON.stringify(errorResponse), {
+          status: 500,
+          headers: {
+            'Content-Type': 'application/json'
+          }
+        });
+      }
+    };
+  };
+};
+
+/**
+ * Composes multiple middleware functions
+ * @param {...Function} middlewares - Middleware functions to compose
+ * @returns {Function} Composed middleware
+ */
+export const composeMiddleware = (...middlewares) => {
+  return middlewares.reduce((composed, middleware) => {
+    return handler => middleware(composed(handler));
+  });
+};

package/docs/FRAMEWORK-ARCHITECTURE-OVERVIEW.md

@@ -0,0 +1,206 @@
+# CLODO Framework Architecture Overview
+
+## Framework Philosophy
+
+The CLODO Framework implements a sophisticated **component-based architecture** where reusable "Clodo bricks" can be snapped together to build complex enterprise applications. Each component handles one concern perfectly, enabling rapid development of autonomous, domain-specific services.
+
+## Core Architecture
+
+### Three-Layer Design
+
+#### 🎯 **Framework Core (Published Package)**
+The main library that downstream applications import and use:
+
+```javascript
+import {
+  GenericDataService,
+  SchemaManager,
+  CrossDomainCoordinator,
+  ConfigurationCacheManager
+} from '@tamyla/clodo-framework';
+```
+
+**Key Components:**
+- **Data Management**: GenericDataService, SchemaManager, DatabaseOrchestrator
+- **Request Handling**: EnhancedRouter, GenericRouteHandler
+- **Configuration**: Domain configs, feature flags, customer management
+- **Orchestration**: Cross-domain coordination, deployment automation
+- **Security**: Configuration validation, secret management
+
+#### 🛠️ **CLI Tools (Development Interface)**
+Command-line tools for development, administration, and deployment:
+
+```bash
+# Interactive deployment
+node bin/deployment/enterprise-deploy.js deploy --interactive
+
+# Database management
+node bin/database/enterprise-db-manager.js migrate api.example.com
+
+# Portfolio operations
+node bin/portfolio/portfolio-manager.js deploy
+```
+
+**Available Tools:**
+- **Deployment CLI**: Interactive and automated deployment workflows
+- **Database CLI**: Migration, backup, health monitoring, optimization
+- **Portfolio CLI**: Multi-domain portfolio management and analytics
+- **Service Management**: Automated service initialization and templates
+
+#### 🔧 **Shared Utilities (Internal Implementation)**
+Internal utilities that power the CLI tools and framework components.
+
+## Intelligent Execution Model
+
+### Smart Component Resolution
+
+The framework uses **intelligent dependency resolution** to automatically:
+- **Discover services** through domain-based configuration
+- **Cache frequently used data** (schemas, queries, configurations)
+- **Pool database connections** with automatic health monitoring
+- **Validate configurations** progressively (syntax → semantic → integration)
+
+### Auto-Discovery & Orchestration
+
+Services automatically find and coordinate with each other through:
+- **Cloudflare API integration** for domain discovery
+- **Configuration inheritance** (global → customer → domain → service)
+- **Dependency graph analysis** for safe deployment ordering
+- **Cross-domain coordination** with failure isolation
+
+## Usage Patterns
+
+### Library Usage (Programmatic)
+**Best for**: Building custom services, integrating with existing codebases
+
+```javascript
+// Direct component usage
+import { GenericDataService, SchemaManager } from '@tamyla/clodo-framework';
+
+const service = new GenericDataService(d1Client, 'users');
+const users = await service.findAll({ limit: 10 });
+```
+
+### CLI Usage (Command Line)
+**Best for**: Development workflows, administration, one-off operations
+
+```bash
+# Deploy a service
+node bin/deployment/enterprise-deploy.js deploy api.example.com
+
+# Manage database
+node bin/database/enterprise-db-manager.js health api.example.com
+```
+
+### Hybrid Approach
+Most teams use both: CLI tools for development/administration, library components for service implementation.
+
+## Key Features
+
+### 🔒 **Security by Default**
+- Automatic security validation on all deployments
+- Environment-specific security requirements
+- Cryptographic key generation and management
+- Prevention of insecure configurations reaching production
+
+### ⚡ **Performance Optimized**
+- Multi-layer caching (schemas, queries, configurations)
+- Connection pooling with health monitoring
+- Lazy component initialization
+- Query optimization and result caching
+
+### 🛡️ **Enterprise Reliable**
+- Circuit breaker patterns for external services
+- Exponential backoff for retries
+- Graceful degradation on failures
+- Comprehensive error recovery
+
+### 📊 **Observable**
+- Built-in performance monitoring
+- Deployment auditing and logging
+- Health checks and alerting
+- Comprehensive telemetry
+
+## Design Principles
+
+### 🎪 **Clodo Architecture**
+- **Single Responsibility**: Each component has one clear purpose
+- **Composability**: Components combine in any configuration
+- **Reusability**: Components work across different contexts
+- **Testability**: Isolated testing of individual components with modular testing capabilities
+- **Modular Testing**: Individual test modules (API, Auth, Database, Performance) for granular control
+- **Observability**: Every operation is logged and monitored
+
+### 🏗️ **Convention over Configuration**
+- Standard patterns reduce decision complexity
+- Sensible defaults with override capabilities
+- Consistent naming and structure
+- Predictable behavior across components
+
+### 🔧 **Modular Extensibility**
+- Service types can be added without core changes
+- Custom validators and adapters can be plugged in
+- Database backends can be swapped
+- Deployment strategies are configurable
+
+## Getting Started
+
+### For Service Developers
+1. **Install**: `npm install @tamyla/clodo-framework`
+2. **Import components** you need for your service
+3. **Configure** domains, features, and database connections
+4. **Deploy** using CLI tools or embed deployment logic
+
+### For Platform Administrators
+1. **Use CLI tools** for deployment and management
+2. **Monitor** services through built-in telemetry
+3. **Configure** multi-tenant environments
+4. **Scale** by adding more domains and services
+
+## Architecture Benefits
+
+### For Small Businesses
+- **Cost Effective**: Generic components = affordable custom software
+- **Fast Time-to-Market**: Configuration over custom development
+- **Scalable**: Start simple, add complexity as you grow
+- **Maintainable**: Framework handles infrastructure complexity
+
+### For Enterprise Teams
+- **Consistency**: Standardized patterns across services
+- **Reliability**: Battle-tested components with enterprise features
+- **Developer Productivity**: Focus on business logic, not infrastructure
+- **Operational Excellence**: Built-in monitoring, security, and automation
+
+## Integration Examples
+
+### Basic CRUD Service
+```javascript
+import { GenericDataService, SchemaManager } from '@tamyla/clodo-framework';
+
+export default {
+  async fetch(request, env) {
+    const service = new GenericDataService(env.DB, 'products');
+    const products = await service.findAll();
+    return Response.json(products);
+  }
+};
+```
+
+### Multi-Domain Orchestration
+```javascript
+import { CrossDomainCoordinator } from '@tamyla/clodo-framework';
+
+const coordinator = new CrossDomainCoordinator({
+  domains: ['api.example.com', 'auth.example.com'],
+  enableMonitoring: true
+});
+
+await coordinator.deployAll();
+```
+
+## Conclusion
+
+The CLODO Framework provides a sophisticated yet approachable way to build enterprise-grade applications. By combining reusable components with intelligent orchestration, it enables both rapid development and enterprise reliability. The dual interface (library + CLI) serves different user needs while maintaining architectural integrity.
+
+Whether you're building a simple CRUD service or a complex multi-domain enterprise application, the framework provides the components and intelligence to get you there efficiently and reliably.</content>
+<parameter name="filePath">c:\Users\Admin\Documents\coding\tamyla\clodo-framework\docs\FRAMEWORK-ARCHITECTURE-OVERVIEW.md