@tamyla/clodo-framework 3.0.15 → 3.1.0

package/dist/service-management/routing/RouteGenerator.js

@@ -0,0 +1,266 @@
+/**
+ * RouteGenerator - Main orchestrator for route generation
+ * 
+ * Generates Cloudflare Workers [[routes]] configuration from domain metadata.
+ * This is a CORE IDENTITY feature that completes multi-domain orchestration.
+ * 
+ * @module service-management/routing/RouteGenerator
+ */
+
+import { DomainRouteMapper } from './DomainRouteMapper.js';
+import { WranglerRoutesBuilder } from './WranglerRoutesBuilder.js';
+import { frameworkConfig } from '../../utils/framework-config.js';
+export class RouteGenerator {
+  constructor(options = {}) {
+    this.mapper = new DomainRouteMapper(options);
+    this.builder = new WranglerRoutesBuilder(options);
+
+    // Load routing configuration from validation-config.json
+    const routingConfig = frameworkConfig.getRoutingConfig();
+    const templateDefaults = frameworkConfig.config.templates?.defaults || {};
+    this.options = {
+      // Routing defaults from config
+      includeComments: routingConfig.defaults.includeComments,
+      includeZoneId: routingConfig.defaults.includeZoneId,
+      environment: routingConfig.defaults.targetEnvironment,
+      // Map targetEnvironment -> environment
+      orderStrategy: routingConfig.defaults.orderStrategy,
+      // Domain configuration
+      workersDomain: templateDefaults.WORKERS_DEV_DOMAIN || 'workers.dev',
+      skipPatterns: routingConfig.domains.skipPatterns,
+      // Allow runtime overrides
+      ...options
+    };
+  }
+
+  /**
+   * Generate routes configuration for wrangler.toml
+   * 
+   * @param {Object} coreInputs - Core service inputs (6 values)
+   * @param {string} coreInputs.serviceName - Service name
+   * @param {string} coreInputs.serviceType - Service type
+   * @param {string} coreInputs.domainName - Domain name
+   * @param {string} coreInputs.cloudflareAccountId - Cloudflare account ID
+   * @param {string} coreInputs.cloudflareZoneId - Cloudflare zone ID (32 hex chars)
+   * @param {string} coreInputs.environment - Environment (production|staging|development)
+   * 
+   * @param {Object} confirmedValues - Confirmed configuration values (15 values)
+   * @param {string} confirmedValues.productionUrl - Production URL (e.g., api.example.com)
+   * @param {string} confirmedValues.stagingUrl - Staging URL (e.g., staging-api.example.com)
+   * @param {string} confirmedValues.developmentUrl - Development URL (optional, defaults to workers.dev)
+   * @param {string} confirmedValues.apiBasePath - API base path (e.g., /api)
+   * @param {string} confirmedValues.workerName - Worker name
+   * 
+   * @param {Object} options - Generation options
+   * @param {boolean} options.includeComments - Include explanatory comments (default: true)
+   * @param {boolean} options.includeZoneId - Include zone_id in routes (default: true)
+   * @param {string} options.environment - Target environment filter (default: 'all')
+   * 
+   * @returns {string} TOML-formatted routes configuration
+   * 
+   * @throws {Error} If domain configuration is invalid or incomplete
+   * 
+   * @example
+   * const routeGenerator = new RouteGenerator();
+   * const routesConfig = routeGenerator.generateRoutes(
+   *   {
+   *     serviceName: 'my-api',
+   *     domainName: 'example.com',
+   *     cloudflareZoneId: 'abc123...',
+   *     // ... other core inputs
+   *   },
+   *   {
+   *     productionUrl: 'api.example.com',
+   *     stagingUrl: 'staging-api.example.com',
+   *     apiBasePath: '/api',
+   *     // ... other confirmed values
+   *   }
+   * );
+   */
+  generateRoutes(coreInputs, confirmedValues, options = {}) {
+    // Merge options
+    const opts = {
+      ...this.options,
+      ...options
+    };
+
+    // Validate inputs
+    this.validateDomainConfig(coreInputs, confirmedValues);
+
+    // Build domain configuration
+    const domainConfig = {
+      domains: {
+        production: confirmedValues.productionUrl,
+        staging: confirmedValues.stagingUrl,
+        development: confirmedValues.developmentUrl
+      },
+      zoneId: coreInputs.cloudflareZoneId,
+      apiBasePath: confirmedValues.apiBasePath,
+      serviceName: coreInputs.serviceName,
+      workerName: confirmedValues.workerName
+    };
+
+    // Generate routes for each environment
+    const productionRoutes = this._generateEnvironmentRoutes(domainConfig, 'production', opts);
+    const stagingRoutes = this._generateEnvironmentRoutes(domainConfig, 'staging', opts);
+    const developmentRoutes = this._generateEnvironmentRoutes(domainConfig, 'development', opts);
+
+    // Build complete routes section
+    let routesSection = '';
+
+    // Add header comment
+    if (opts.includeComments) {
+      routesSection += `# Routes configuration for ${domainConfig.serviceName}\n`;
+      routesSection += `# Generated by Clodo Framework RouteGenerator\n`;
+      routesSection += `# Generated: ${new Date().toISOString()}\n\n`;
+    }
+
+    // Add production routes (top-level)
+    if (productionRoutes && (opts.environment === 'all' || opts.environment === 'production')) {
+      routesSection += productionRoutes;
+    }
+
+    // Add staging routes
+    if (stagingRoutes && (opts.environment === 'all' || opts.environment === 'staging')) {
+      if (routesSection && !routesSection.endsWith('\n\n')) {
+        routesSection += '\n';
+      }
+      routesSection += stagingRoutes;
+    }
+
+    // Add development routes (usually none - workers.dev)
+    if (developmentRoutes && (opts.environment === 'all' || opts.environment === 'development')) {
+      if (routesSection && !routesSection.endsWith('\n\n')) {
+        routesSection += '\n';
+      }
+      routesSection += developmentRoutes;
+    }
+    return routesSection.trim() + '\n';
+  }
+
+  /**
+   * Generate routes for a specific environment
+   * @private
+   */
+  _generateEnvironmentRoutes(domainConfig, environment, options) {
+    const domainUrl = domainConfig.domains[environment];
+
+    // Skip if no domain configured or matches skip patterns
+    if (!domainUrl || this._shouldSkipDomain(domainUrl)) {
+      // workers.dev subdomain - no routes needed
+      if (environment === 'development' && options.includeComments) {
+        return this.builder.generateDevComment(domainConfig.workerName);
+      }
+      return '';
+    }
+
+    // Map domain to route patterns
+    const routeMapping = this.mapper.mapDomainToRoutes(domainConfig, environment);
+
+    // Build TOML routes section
+    return this.builder.buildRoutesSection(routeMapping.patterns, environment, {
+      zoneId: options.includeZoneId ? routeMapping.zoneId : null,
+      includeComments: options.includeComments,
+      domain: domainUrl,
+      serviceName: domainConfig.serviceName
+    });
+  }
+
+  /**
+   * Validate domain configuration completeness
+   * 
+   * @param {Object} coreInputs - Core service inputs
+   * @param {Object} confirmedValues - Confirmed configuration values
+   * @throws {Error} If validation fails
+   */
+  validateDomainConfig(coreInputs, confirmedValues) {
+    // Check required coreInputs
+    if (!coreInputs) {
+      throw new Error('coreInputs is required for route generation');
+    }
+    if (!coreInputs.serviceName) {
+      throw new Error('coreInputs.serviceName is required for route generation');
+    }
+    if (!coreInputs.cloudflareZoneId) {
+      throw new Error('coreInputs.cloudflareZoneId is required for route generation');
+    }
+
+    // Validate zone_id format (32 hex characters)
+    const zoneIdPattern = /^[a-f0-9]{32}$/;
+    if (!zoneIdPattern.test(coreInputs.cloudflareZoneId)) {
+      throw new Error('coreInputs.cloudflareZoneId must be a valid Cloudflare zone ID (32 hex characters). ' + `Received: "${coreInputs.cloudflareZoneId}"`);
+    }
+
+    // Check required confirmedValues
+    if (!confirmedValues) {
+      throw new Error('confirmedValues is required for route generation');
+    }
+    if (!confirmedValues.productionUrl) {
+      throw new Error('confirmedValues.productionUrl is required for route generation');
+    }
+
+    // Validate production URL format
+    if (!this._isValidDomain(confirmedValues.productionUrl)) {
+      throw new Error('confirmedValues.productionUrl must be a valid domain name. ' + `Received: "${confirmedValues.productionUrl}"`);
+    }
+  }
+
+  /**
+   * Check if a string is a valid domain name
+   * @private
+   */
+  _isValidDomain(domain) {
+    if (!domain || typeof domain !== 'string') {
+      return false;
+    }
+
+    // Basic domain validation
+    const domainPattern = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/i;
+    return domainPattern.test(domain);
+  }
+
+  /**
+   * Get route patterns for a specific domain and environment
+   * 
+   * @param {string} domain - Domain name (e.g., api.example.com)
+   * @param {string} environment - Environment (production|staging|development)
+   * @param {Object} options - Additional options
+   * @returns {Array<string>} Array of route patterns
+   * 
+   * @example
+   * const patterns = routeGenerator.getRoutePatterns('api.example.com', 'production');
+   * // Returns: ['api.example.com/*', 'example.com/api/*']
+   */
+  getRoutePatterns(domain, environment, options = {}) {
+    const domainConfig = {
+      domains: {
+        [environment]: domain
+      },
+      zoneId: options.zoneId || 'placeholder',
+      apiBasePath: options.apiBasePath,
+      serviceName: options.serviceName || 'service'
+    };
+    const routeMapping = this.mapper.mapDomainToRoutes(domainConfig, environment);
+    return routeMapping.patterns;
+  }
+
+  /**
+   * Check if a domain should be skipped for route generation
+   * @private
+   * 
+   * @param {string} domain - Domain to check
+   * @returns {boolean} True if domain should be skipped
+   */
+  _shouldSkipDomain(domain) {
+    if (!domain) return true;
+
+    // Check workers.dev domain
+    if (domain.includes(this.options.workersDomain)) {
+      return true;
+    }
+
+    // Check configured skip patterns
+    const skipPatterns = this.options.skipPatterns || [];
+    return skipPatterns.some(pattern => domain.includes(pattern));
+  }
+}

package/dist/service-management/routing/WranglerRoutesBuilder.js

@@ -0,0 +1,273 @@
+/**
+ * WranglerRoutesBuilder - Builds TOML [[routes]] sections
+ * 
+ * Formats route patterns as valid TOML with proper syntax,
+ * comments, and environment-specific sections.
+ * 
+ * @module service-management/routing/WranglerRoutesBuilder
+ */
+
+export class WranglerRoutesBuilder {
+  constructor(options = {}) {
+    this.options = options;
+  }
+
+  /**
+   * Build TOML [[routes]] section
+   * 
+   * @param {Array<string>} patterns - Array of route patterns
+   * @param {string} environment - Target environment (production|staging|development)
+   * @param {Object} options - Build options
+   * @param {string} options.zoneId - Cloudflare zone ID (optional)
+   * @param {boolean} options.includeComments - Include comments (default: true)
+   * @param {string} options.domain - Domain name (for comments)
+   * @param {string} options.serviceName - Service name (for comments)
+   * 
+   * @returns {string} TOML-formatted routes section
+   * 
+   * @example
+   * const builder = new WranglerRoutesBuilder();
+   * const toml = builder.buildRoutesSection(
+   *   ['api.example.com/*', 'example.com/api/*'],
+   *   'production',
+   *   { zoneId: 'xyz789...', includeComments: true, domain: 'api.example.com' }
+   * );
+   */
+  buildRoutesSection(patterns, environment, options = {}) {
+    if (!patterns || patterns.length === 0) {
+      return '';
+    }
+    const opts = {
+      includeComments: options.includeComments !== false,
+      ...options
+    };
+    let section = '';
+
+    // Add environment comment
+    if (opts.includeComments) {
+      section += this.generateRouteComment(opts.domain || 'unknown', environment);
+      section += '\n';
+    }
+
+    // Determine if routes should be nested under environment
+    const isNested = environment === 'staging' || environment === 'development';
+    const prefix = isNested ? `env.${environment}.` : '';
+
+    // Build each route
+    patterns.forEach((pattern, index) => {
+      section += this.formatRoutePattern(pattern, opts.zoneId, prefix);
+
+      // Add spacing between routes (but not after last one)
+      if (index < patterns.length - 1) {
+        section += '\n';
+      }
+    });
+    return section;
+  }
+
+  /**
+   * Format a single route pattern as TOML
+   * 
+   * @param {string} pattern - Route pattern (e.g., api.example.com/*)
+   * @param {string} zoneId - Cloudflare zone ID (optional)
+   * @param {string} prefix - Environment prefix (e.g., 'env.staging.')
+   * @returns {string} TOML-formatted route
+   * 
+   * @example
+   * formatRoutePattern('api.example.com/*', 'xyz789...')
+   * // Returns:
+   * // [[routes]]
+   * // pattern = "api.example.com/*"
+   * // zone_id = "xyz789..."
+   */
+  formatRoutePattern(pattern, zoneId = null, prefix = '') {
+    let toml = `[[${prefix}routes]]\n`;
+    toml += `pattern = "${this._escapeTomlString(pattern)}"\n`;
+    if (zoneId) {
+      toml += `zone_id = "${this._escapeTomlString(zoneId)}"\n`;
+    }
+    return toml;
+  }
+
+  /**
+   * Generate descriptive comment for routes
+   * 
+   * @param {string} domain - Domain name
+   * @param {string} environment - Environment name
+   * @returns {string} Comment text
+   * 
+   * @example
+   * generateRouteComment('api.example.com', 'production')
+   * // Returns: "# Production environment routes\n# Domain: api.example.com"
+   */
+  generateRouteComment(domain, environment) {
+    const envName = environment.charAt(0).toUpperCase() + environment.slice(1);
+    let comment = `# ${envName} environment routes\n`;
+    comment += `# Domain: ${domain}`;
+    return comment;
+  }
+
+  /**
+   * Generate development environment comment
+   * 
+   * Used when development uses workers.dev subdomain (no routes needed)
+   * 
+   * @param {string} workerName - Worker name
+   * @returns {string} Comment explaining workers.dev usage
+   */
+  generateDevComment(workerName) {
+    return `# Development environment\n` + `# Uses workers.dev subdomain: https://${workerName}-dev.<account>.workers.dev\n` + `# No custom domain routes needed for development\n`;
+  }
+
+  /**
+   * Validate TOML syntax
+   * 
+   * Basic validation to catch common TOML errors
+   * 
+   * @param {string} tomlString - TOML string to validate
+   * @returns {Object} Validation result
+   * @returns {boolean} returns.valid - True if valid TOML syntax
+   * @returns {Array<string>} returns.errors - Array of error messages
+   * 
+   * @example
+   * const result = builder.validateTomlSyntax('[[routes]]\npattern = "api.example.com/*"');
+   * // Returns: { valid: true, errors: [] }
+   */
+  validateTomlSyntax(tomlString) {
+    const errors = [];
+    if (!tomlString || typeof tomlString !== 'string') {
+      return {
+        valid: false,
+        errors: ['TOML string is required']
+      };
+    }
+    const lines = tomlString.split('\n');
+    lines.forEach((line, index) => {
+      const lineNum = index + 1;
+      const trimmed = line.trim();
+
+      // Skip empty lines and comments
+      if (!trimmed || trimmed.startsWith('#')) {
+        return;
+      }
+
+      // Check [[array]] syntax
+      if (trimmed.startsWith('[[')) {
+        if (!trimmed.endsWith(']]')) {
+          errors.push(`Line ${lineNum}: Invalid [[array]] syntax - missing closing ]]`);
+        }
+        const arrayName = trimmed.slice(2, -2);
+        if (!arrayName) {
+          errors.push(`Line ${lineNum}: Empty [[array]] name`);
+        }
+      }
+
+      // Check [section] syntax
+      else if (trimmed.startsWith('[') && !trimmed.startsWith('[[')) {
+        if (!trimmed.endsWith(']')) {
+          errors.push(`Line ${lineNum}: Invalid [section] syntax - missing closing ]`);
+        }
+        const sectionName = trimmed.slice(1, -1);
+        if (!sectionName) {
+          errors.push(`Line ${lineNum}: Empty [section] name`);
+        }
+      }
+
+      // Check key = value syntax
+      else if (trimmed.includes('=')) {
+        const parts = trimmed.split('=');
+        if (parts.length !== 2) {
+          errors.push(`Line ${lineNum}: Invalid key = value syntax - multiple equals signs`);
+          return;
+        }
+        const key = parts[0].trim();
+        const value = parts[1].trim();
+        if (!key) {
+          errors.push(`Line ${lineNum}: Missing key before =`);
+        }
+        if (!value) {
+          errors.push(`Line ${lineNum}: Missing value after =`);
+        }
+
+        // Check string values are quoted
+        if (value && !value.startsWith('"') && !value.match(/^[0-9]+$/)) {
+          // Not a number and not quoted
+          if (!value.startsWith('[') && !value.match(/^(true|false)$/)) {
+            errors.push(`Line ${lineNum}: String values must be quoted (key: ${key})`);
+          }
+        }
+
+        // Check for unescaped quotes
+        if (value.startsWith('"') && value.endsWith('"')) {
+          const innerValue = value.slice(1, -1);
+          if (innerValue.includes('"') && !innerValue.includes('\\"')) {
+            errors.push(`Line ${lineNum}: Unescaped quote in string value (key: ${key})`);
+          }
+        }
+      }
+    });
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Escape special characters for TOML strings
+   * @private
+   * 
+   * @param {string} str - String to escape
+   * @returns {string} Escaped string
+   */
+  _escapeTomlString(str) {
+    if (!str) return '';
+    return str.replace(/\\/g, '\\\\') // Escape backslashes
+    .replace(/"/g, '\\"') // Escape quotes
+    .replace(/\n/g, '\\n') // Escape newlines
+    .replace(/\r/g, '\\r') // Escape carriage returns
+    .replace(/\t/g, '\\t'); // Escape tabs
+  }
+
+  /**
+   * Build complete wrangler.toml routes configuration
+   * 
+   * High-level method that builds routes for all environments
+   * 
+   * @param {Object} routesByEnvironment - Routes grouped by environment
+   * @param {Array<string>} routesByEnvironment.production - Production routes
+   * @param {Array<string>} routesByEnvironment.staging - Staging routes
+   * @param {Array<string>} routesByEnvironment.development - Development routes
+   * @param {Object} options - Build options
+   * 
+   * @returns {string} Complete TOML routes configuration
+   */
+  buildCompleteRoutesConfig(routesByEnvironment, options = {}) {
+    let config = '';
+
+    // Add header
+    if (options.includeComments !== false) {
+      config += '# Cloudflare Workers Routes Configuration\n';
+      config += '# Generated by Clodo Framework\n';
+      config += `# Generated: ${new Date().toISOString()}\n\n`;
+    }
+
+    // Production routes (top-level)
+    if (routesByEnvironment.production && routesByEnvironment.production.length > 0) {
+      config += this.buildRoutesSection(routesByEnvironment.production, 'production', options);
+      config += '\n\n';
+    }
+
+    // Staging routes
+    if (routesByEnvironment.staging && routesByEnvironment.staging.length > 0) {
+      config += this.buildRoutesSection(routesByEnvironment.staging, 'staging', options);
+      config += '\n\n';
+    }
+
+    // Development routes
+    if (routesByEnvironment.development && routesByEnvironment.development.length > 0) {
+      config += this.buildRoutesSection(routesByEnvironment.development, 'development', options);
+      config += '\n\n';
+    }
+    return config.trim() + '\n';
+  }
+}

package/dist/service-management/routing/index.js

@@ -0,0 +1,14 @@
+/**
+ * Routing module exports
+ * 
+ * Provides automatic route generation for Cloudflare Workers
+ * from domain configuration metadata.
+ * 
+ * This is a CORE IDENTITY feature that completes multi-domain orchestration.
+ * 
+ * @module service-management/routing
+ */
+
+export { RouteGenerator } from './RouteGenerator.js';
+export { DomainRouteMapper } from './DomainRouteMapper.js';
+export { WranglerRoutesBuilder } from './WranglerRoutesBuilder.js';

package/dist/service-management/services/DirectoryStructureService.js

@@ -0,0 +1,56 @@
+/**
+ * DirectoryStructureService - Handles creation of directory structures for services
+ * 
+ * Provides standardized directory layout creation for generated services,
+ * ensuring consistent project structure across all service types.
+ */
+import { existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+export class DirectoryStructureService {
+  /**
+   * Create the standard directory structure for a service
+   * @param {string} servicePath - Root path of the service
+   */
+  createStandardStructure(servicePath) {
+    const directories = ['src', 'src/config', 'src/worker', 'src/handlers', 'src/middleware', 'src/utils', 'src/schemas', 'scripts', 'test', 'test/unit', 'test/integration', 'docs', 'config', 'logs', '.github', '.github/workflows'];
+    for (const dir of directories) {
+      const fullPath = join(servicePath, dir);
+      if (!existsSync(fullPath)) {
+        mkdirSync(fullPath, {
+          recursive: true
+        });
+      }
+    }
+  }
+
+  /**
+   * Create a custom directory structure
+   * @param {string} servicePath - Root path of the service
+   * @param {string[]} directories - Array of directory paths to create
+   */
+  createCustomStructure(servicePath, directories) {
+    for (const dir of directories) {
+      const fullPath = join(servicePath, dir);
+      if (!existsSync(fullPath)) {
+        mkdirSync(fullPath, {
+          recursive: true
+        });
+      }
+    }
+  }
+
+  /**
+   * Ensure a single directory exists
+   * @param {string} directoryPath - Full path to the directory
+   * @returns {boolean} - True if directory was created, false if it already existed
+   */
+  ensureDirectory(directoryPath) {
+    if (!existsSync(directoryPath)) {
+      mkdirSync(directoryPath, {
+        recursive: true
+      });
+      return true;
+    }
+    return false;
+  }
+}