@tamyla/clodo-framework 4.0.11 → 4.0.12

package/CHANGELOG.md

@@ -1,8 +1,51 @@
-## [4.0.11](https://github.com/tamylaa/clodo-framework/compare/v4.0.10...v4.0.11) (2025-12-11)
+## [4.0.12](https://github.com/tamylaa/clodo-framework/compare/v4.0.11...v4.0.12) (2025-12-12)
 
 
 ### Bug Fixes
 
+* resolve version sync for 4.0.12 release ([6375c5f](https://github.com/tamylaa/clodo-framework/commit/6375c5f71516cf2a7a96edcf5878106063037ba8))
+* trigger 4.0.12 release after tag sync ([3dafb25](https://github.com/tamylaa/clodo-framework/commit/3dafb253cbbae6e7eac27dd5170e9f391c3deda0))
+
+## [4.0.11](https://github.com/tamylaa/clodo-framework/compare/v4.0.10...v4.0.11) (2025-12-12)
+
+
+### Bug Fixes
+
+* add wrangler compatibility and config validation utilities ([98c745b](https://github.com/tamylaa/clodo-framework/commit/98c745bb72608a4d5808c947cc9c7a39b868243f))
+* correct import path in file-manager.js for proper dist compilation ([166698e](https://github.com/tamylaa/clodo-framework/commit/166698ebb9473ba5d889739831a1d4e1040c12a5))
+* correct NPM_TOKEN environment variable name in GitHub Actions workflow ([938c953](https://github.com/tamylaa/clodo-framework/commit/938c953d7e2e9f1a679ee566f1a4c7a070e629e6))
+* resolve version sync for 4.0.12 release ([6375c5f](https://github.com/tamylaa/clodo-framework/commit/6375c5f71516cf2a7a96edcf5878106063037ba8))
+* trigger patch release for latest changes ([6161573](https://github.com/tamylaa/clodo-framework/commit/6161573ead8271eaea2766bf7c85f63ef7378a7d))
+* update .gitignore to prevent test artifacts from being tracked ([83457d5](https://github.com/tamylaa/clodo-framework/commit/83457d58b1e8d44865a593b2b75e39f4509a75bf))
+
+## [4.0.11](https://github.com/tamylaa/clodo-framework/compare/v4.0.10...v4.0.11) (2025-12-12)
+
+
+### Bug Fixes
+
+* add wrangler compatibility and config validation utilities ([98c745b](https://github.com/tamylaa/clodo-framework/commit/98c745bb72608a4d5808c947cc9c7a39b868243f))
+* correct import path in file-manager.js for proper dist compilation ([166698e](https://github.com/tamylaa/clodo-framework/commit/166698ebb9473ba5d889739831a1d4e1040c12a5))
+* correct NPM_TOKEN environment variable name in GitHub Actions workflow ([938c953](https://github.com/tamylaa/clodo-framework/commit/938c953d7e2e9f1a679ee566f1a4c7a070e629e6))
+* trigger patch release for latest changes ([6161573](https://github.com/tamylaa/clodo-framework/commit/6161573ead8271eaea2766bf7c85f63ef7378a7d))
+* update .gitignore to prevent test artifacts from being tracked ([83457d5](https://github.com/tamylaa/clodo-framework/commit/83457d58b1e8d44865a593b2b75e39f4509a75bf))
+
+## [4.0.11](https://github.com/tamylaa/clodo-framework/compare/v4.0.10...v4.0.11) (2025-12-12)
+
+
+### Bug Fixes
+
+* add wrangler compatibility and config validation utilities ([98c745b](https://github.com/tamylaa/clodo-framework/commit/98c745bb72608a4d5808c947cc9c7a39b868243f))
+* correct import path in file-manager.js for proper dist compilation ([166698e](https://github.com/tamylaa/clodo-framework/commit/166698ebb9473ba5d889739831a1d4e1040c12a5))
+* correct NPM_TOKEN environment variable name in GitHub Actions workflow ([938c953](https://github.com/tamylaa/clodo-framework/commit/938c953d7e2e9f1a679ee566f1a4c7a070e629e6))
+* update .gitignore to prevent test artifacts from being tracked ([83457d5](https://github.com/tamylaa/clodo-framework/commit/83457d58b1e8d44865a593b2b75e39f4509a75bf))
+
+## [4.0.11](https://github.com/tamylaa/clodo-framework/compare/v4.0.10...v4.0.11) (2025-12-12)
+
+
+### Bug Fixes
+
+* add wrangler compatibility and config validation utilities ([98c745b](https://github.com/tamylaa/clodo-framework/commit/98c745bb72608a4d5808c947cc9c7a39b868243f))
+* correct import path in file-manager.js for proper dist compilation ([166698e](https://github.com/tamylaa/clodo-framework/commit/166698ebb9473ba5d889739831a1d4e1040c12a5))
 * correct NPM_TOKEN environment variable name in GitHub Actions workflow ([938c953](https://github.com/tamylaa/clodo-framework/commit/938c953d7e2e9f1a679ee566f1a4c7a070e629e6))
 * update .gitignore to prevent test artifacts from being tracked ([83457d5](https://github.com/tamylaa/clodo-framework/commit/83457d58b1e8d44865a593b2b75e39f4509a75bf))
 

package/dist/cli/commands/assess.js

@@ -5,7 +5,8 @@
 
 import chalk from 'chalk';
 import path from 'path';
-import { ServiceOrchestrator, StandardOptions, ServiceConfigManager } from '@tamyla/clodo-framework';
+import { ServiceOrchestrator, ServiceConfigManager } from '@tamyla/clodo-framework';
+import { StandardOptions } from '../../lib/shared/utils/cli-options.js';
 export function registerAssessCommand(program) {
   const command = program.command('assess [service-path]').description('Run intelligent capability assessment (requires @tamyla/clodo-orchestration)').option('--export <file>', 'Export assessment results to JSON file').option('--domain <domain>', 'Domain name for assessment').option('--service-type <type>', 'Service type for assessment').option('--token <token>', 'Cloudflare API token').option('--show-config-sources', 'Display all configuration sources and merged result');
 

package/dist/cli/commands/create.js

@@ -6,7 +6,8 @@
  */
 
 import chalk from 'chalk';
-import { Clodo, StandardOptions, ConfigLoader } from '@tamyla/clodo-framework';
+import { Clodo, ConfigLoader } from '@tamyla/clodo-framework';
+import { StandardOptions } from '../../lib/shared/utils/cli-options.js';
 export function registerCreateCommand(program) {
   const command = program.command('create').description('Create a new Clodo service with conversational setup').option('-n, --non-interactive', 'Run in non-interactive mode with all required parameters').option('--service-name <name>', 'Service name (required in non-interactive mode)').option('--service-type <type>', 'Service type: data-service, auth-service, content-service, api-gateway, generic', 'generic').option('--domain-name <domain>', 'Domain name (required in non-interactive mode)').option('--cloudflare-token <token>', 'Cloudflare API token (required in non-interactive mode)').option('--cloudflare-account-id <id>', 'Cloudflare account ID (required in non-interactive mode)').option('--cloudflare-zone-id <id>', 'Cloudflare zone ID (required in non-interactive mode)').option('--environment <env>', 'Target environment: development, staging, production', 'development').option('--output-path <path>', 'Output directory for generated service', '.').option('--template-path <path>', 'Path to service templates', './templates').option('--force', 'Skip confirmation prompts').option('--validate', 'Validate service after creation');
 

package/dist/cli/commands/deploy.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
-import { Clodo, StandardOptions, ConfigLoader, InteractiveDeploymentCoordinator, OutputFormatter } from '@tamyla/clodo-framework';
+import { Clodo, ConfigLoader, InteractiveDeploymentCoordinator, OutputFormatter } from '@tamyla/clodo-framework';
+import { StandardOptions } from '../../lib/shared/utils/cli-options.js';
 export function registerDeployCommand(program) {
   const command = program.command('deploy').description('Deploy a Clodo service with interactive configuration and validation')
   // Cloudflare-specific options

package/dist/cli/commands/diagnose.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import path from 'path';
-import { ServiceOrchestrator, StandardOptions, ServiceConfigManager } from '@tamyla/clodo-framework';
+import { ServiceOrchestrator, ServiceConfigManager } from '@tamyla/clodo-framework';
+import { StandardOptions } from '../../lib/shared/utils/cli-options.js';
 export function registerDiagnoseCommand(program) {
   const command = program.command('diagnose [service-path]').description('Diagnose and report issues with an existing service').option('--deep-scan', 'Perform deep analysis including dependencies and deployment readiness').option('--export-report <file>', 'Export diagnostic report to file').option('--fix-suggestions', 'Include suggested fixes for issues').option('--show-config-sources', 'Display all configuration sources and merged result');
 

package/dist/cli/commands/update.js

@@ -4,7 +4,8 @@
 
 import chalk from 'chalk';
 import path from 'path';
-import { ServiceOrchestrator, StandardOptions, ServiceConfigManager } from '@tamyla/clodo-framework';
+import { ServiceOrchestrator, ServiceConfigManager } from '@tamyla/clodo-framework';
+import { StandardOptions } from '../../lib/shared/utils/cli-options.js';
 export function registerUpdateCommand(program) {
   const command = program.command('update [service-path]').description('Update an existing service configuration').option('-i, --interactive', 'Run in interactive mode to select what to update').option('--domain-name <domain>', 'Update domain name').option('--cloudflare-token <token>', 'Update Cloudflare API token').option('--cloudflare-account-id <id>', 'Update Cloudflare account ID').option('--cloudflare-zone-id <id>', 'Update Cloudflare zone ID').option('--environment <env>', 'Update target environment: development, staging, production').option('--add-feature <feature>', 'Add a feature flag').option('--remove-feature <feature>', 'Remove a feature flag').option('--regenerate-configs', 'Regenerate all configuration files').option('--fix-errors', 'Attempt to fix common configuration errors').option('--preview', 'Show what would be changed without applying').option('--show-config-sources', 'Display all configuration sources and merged result').option('--force', 'Skip confirmation prompts');
 

package/dist/cli/commands/validate.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
-import { Clodo, StandardOptions } from '@tamyla/clodo-framework';
+import { Clodo } from '@tamyla/clodo-framework';
+import { StandardOptions } from '../../lib/shared/utils/cli-options.js';
 export function registerValidateCommand(program) {
   const command = program.command('validate <service-path>').description('Validate an existing service configuration').option('--export-report <file>', 'Export validation report to JSON file');
 

package/dist/lib/shared/utils/configuration-validator.js

@@ -0,0 +1,250 @@
+/**
+ * Configuration Validator
+ *
+ * Validates service configurations before deployment to catch issues early
+ * and provide actionable error messages.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { WranglerCompatibilityDetector } from './wrangler-compatibility.js';
+export class ConfigurationValidator {
+  /**
+   * Validate a service configuration
+   * @param {string} servicePath - Path to the service directory
+   * @returns {Promise<ValidationResult>} Validation result
+   */
+  static async validateServiceConfig(servicePath) {
+    const result = {
+      isValid: true,
+      errors: [],
+      warnings: [],
+      suggestions: []
+    };
+    try {
+      // Check if wrangler.toml exists
+      const wranglerPath = join(servicePath, 'wrangler.toml');
+      if (!existsSync(wranglerPath)) {
+        result.isValid = false;
+        result.errors.push('Missing wrangler.toml file');
+        result.suggestions.push('Run: npx clodo-service create --service-name <name>');
+        return result;
+      }
+
+      // Load and parse wrangler.toml
+      const wranglerConfig = ConfigurationValidator.parseWranglerToml(wranglerPath);
+      if (!wranglerConfig) {
+        result.isValid = false;
+        result.errors.push('Invalid wrangler.toml format');
+        return result;
+      }
+
+      // Validate required fields
+      ConfigurationValidator.validateRequiredFields(wranglerConfig, result);
+
+      // Validate compatibility configuration
+      await ConfigurationValidator.validateCompatibilityConfig(wranglerConfig, result);
+
+      // Validate build configuration
+      ConfigurationValidator.validateBuildConfig(wranglerConfig, result);
+
+      // Check for common issues
+      ConfigurationValidator.checkCommonIssues(servicePath, wranglerConfig, result);
+    } catch (error) {
+      result.isValid = false;
+      result.errors.push(`Configuration validation failed: ${error.message}`);
+    }
+    return result;
+  }
+
+  /**
+   * Parse wrangler.toml file
+   * @param {string} filePath - Path to wrangler.toml
+   * @returns {Object|null} Parsed configuration or null if invalid
+   */
+  static parseWranglerToml(filePath) {
+    try {
+      const content = readFileSync(filePath, 'utf8');
+      // Simple TOML-like parsing (basic implementation)
+      const config = {};
+      const lines = content.split('\n').map(line => line.trim()).filter(line => line && !line.startsWith('#'));
+      let currentSection = null;
+      for (const line of lines) {
+        if (line.startsWith('[') && line.endsWith(']')) {
+          currentSection = line.slice(1, -1);
+          config[currentSection] = {};
+        } else if (line.includes('=')) {
+          const [key, ...valueParts] = line.split('=');
+          const value = valueParts.join('=').trim();
+          if (currentSection) {
+            config[currentSection][key.trim()] = this.parseValue(value);
+          } else {
+            config[key.trim()] = this.parseValue(value);
+          }
+        }
+      }
+      return config;
+    } catch (error) {
+      console.warn(`Failed to parse wrangler.toml: ${error.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Parse TOML value
+   * @param {string} value - Raw value string
+   * @returns {any} Parsed value
+   */
+  static parseValue(value) {
+    // Remove quotes
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      return value.slice(1, -1);
+    }
+
+    // Parse booleans
+    if (value === 'true') return true;
+    if (value === 'false') return false;
+
+    // Parse arrays (basic)
+    if (value.startsWith('[') && value.endsWith(']')) {
+      try {
+        return JSON.parse(value);
+      } catch {
+        return value;
+      }
+    }
+    return value;
+  }
+
+  /**
+   * Validate required fields
+   * @param {Object} config - Wrangler configuration
+   * @param {ValidationResult} result - Validation result to update
+   */
+  static validateRequiredFields(config, result) {
+    const required = ['name', 'main', 'compatibility_date', 'account_id'];
+    for (const field of required) {
+      if (!config[field]) {
+        result.isValid = false;
+        result.errors.push(`Missing required field: ${field}`);
+      }
+    }
+
+    // Check for D1 databases
+    if (config['d1_databases'] || config['[[d1_databases]]']) {
+      if (!config['d1_databases']?.binding || !config['[[d1_databases]]']?.binding) {
+        result.warnings.push('D1 database configured but binding not specified');
+      }
+    }
+  }
+
+  /**
+   * Validate compatibility configuration
+   * @param {Object} config - Wrangler configuration
+   * @param {ValidationResult} result - Validation result to update
+   */
+  static async validateCompatibilityConfig(config, result) {
+    try {
+      const detector = new WranglerCompatibilityDetector();
+      const wranglerVersion = await Promise.race([detector.detectVersion(), new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), 2000))]);
+      const optimalConfig = detector.getOptimalConfig(wranglerVersion);
+
+      // Check if current config matches optimal
+      if (optimalConfig.nodejs_compat !== undefined) {
+        if (config.nodejs_compat !== optimalConfig.nodejs_compat) {
+          result.warnings.push(`nodejs_compat should be ${optimalConfig.nodejs_compat} for Wrangler ${wranglerVersion}`);
+          result.suggestions.push('Consider updating compatibility configuration');
+        }
+      } else if (optimalConfig.compatibility_flags) {
+        const currentFlags = config.compatibility_flags;
+        if (!currentFlags || !Array.isArray(currentFlags) || !ConfigurationValidator.arraysEqual(currentFlags, optimalConfig.compatibility_flags)) {
+          result.warnings.push(`compatibility_flags should be ${JSON.stringify(optimalConfig.compatibility_flags)} for Wrangler ${wranglerVersion}`);
+          result.suggestions.push('Consider updating compatibility configuration');
+        }
+      }
+    } catch (error) {
+      result.warnings.push(`Could not validate compatibility configuration: ${error.message}`);
+    }
+  }
+
+  /**
+   * Validate build configuration
+   * @param {Object} config - Wrangler configuration
+   * @param {ValidationResult} result - Validation result to update
+   */
+  static validateBuildConfig(config, result) {
+    const build = config.build || {};
+
+    // Check for build command
+    if (!build.command) {
+      result.warnings.push('No build command specified - deployment may fail if code needs compilation');
+      result.suggestions.push('Add: [build] command = "npm run build"');
+    }
+
+    // Check for upload format
+    const upload = build.upload || {};
+    if (!upload.format) {
+      result.warnings.push('No upload format specified - using default may cause issues');
+      result.suggestions.push('Add: [build.upload] format = "modules"');
+    }
+
+    // Check for external includes (important for Node.js modules)
+    const external = upload.external || {};
+    if (!external.include || !external.include.includes('node:*')) {
+      result.warnings.push('Node.js modules may not be properly externalized');
+      result.suggestions.push('Add: [build.upload.external] include = ["node:*"]');
+    }
+  }
+
+  /**
+   * Check for common configuration issues
+   * @param {string} servicePath - Service directory path
+   * @param {Object} config - Wrangler configuration
+   * @param {ValidationResult} result - Validation result to update
+   */
+  static checkCommonIssues(servicePath, config, result) {
+    // Check if main file exists
+    if (config.main) {
+      const mainPath = join(servicePath, config.main);
+      if (!existsSync(mainPath)) {
+        result.isValid = false;
+        result.errors.push(`Main file does not exist: ${config.main}`);
+        result.suggestions.push('Ensure the main file exists or update the main field in wrangler.toml');
+      }
+    }
+
+    // Check for environment variables without values
+    const vars = config.vars || {};
+    for (const [key, value] of Object.entries(vars)) {
+      if (value === '' || value === '""') {
+        result.warnings.push(`Environment variable ${key} has empty value`);
+      }
+    }
+
+    // Check for database_id placeholders
+    if (config['d1_databases']?.database_id === '') {
+      result.warnings.push('D1 database_id is empty - needs to be configured before deployment');
+      result.suggestions.push('Run: wrangler d1 create <database-name>');
+    }
+  }
+
+  /**
+   * Check if two arrays are equal
+   * @param {Array} a - First array
+   * @param {Array} b - Second array
+   * @returns {boolean} True if arrays are equal
+   */
+  static arraysEqual(a, b) {
+    if (a.length !== b.length) return false;
+    return a.every((val, index) => val === b[index]);
+  }
+}
+
+/**
+ * Validation result interface
+ * @typedef {Object} ValidationResult
+ * @property {boolean} isValid - Whether configuration is valid
+ * @property {string[]} errors - Critical errors that prevent deployment
+ * @property {string[]} warnings - Non-critical issues that should be addressed
+ * @property {string[]} suggestions - Actionable suggestions for improvement
+ */

package/dist/lib/shared/utils/wrangler-compatibility.js

@@ -0,0 +1,191 @@
+/**
+ * Wrangler Compatibility Detector
+ *
+ * Automatically detects Wrangler version and provides optimal configuration
+ * to prevent deployment failures due to compatibility issues.
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
+
+/**
+ * Wrangler Compatibility Detector
+ * Handles version detection and optimal configuration generation
+ */
+export class WranglerCompatibilityDetector {
+  /**
+   * Detects the installed Wrangler version
+   * @returns {Promise<string>} Wrangler version string
+   */
+  async detectVersion() {
+    try {
+      const {
+        stdout
+      } = await execAsync('npx wrangler --version');
+      const version = stdout.trim();
+
+      // Validate version format (e.g., "3.15.0", "4.0.0")
+      if (!this.isValidVersion(version)) {
+        console.warn(`⚠️  Detected Wrangler version '${version}' may not be valid. Using fallback detection.`);
+        return this.fallbackDetection();
+      }
+      return version;
+    } catch (error) {
+      console.warn(`⚠️  Failed to detect Wrangler version: ${error.message}`);
+      return this.fallbackDetection();
+    }
+  }
+
+  /**
+   * Validates version string format
+   * @param {string} version - Version string to validate
+   * @returns {boolean} True if version format is valid
+   */
+  isValidVersion(version) {
+    // Match semantic versioning (e.g., 3.15.0, 4.0.0-beta.1)
+    const versionRegex = /^\d+\.\d+\.\d+(-[\w\.\-]+)?$/;
+    return versionRegex.test(version);
+  }
+
+  /**
+   * Fallback version detection when direct detection fails
+   * @returns {string} Fallback version string
+   */
+  fallbackDetection() {
+    // Check for wrangler in package.json
+    try {
+      const fs = require('fs');
+      const path = require('path');
+
+      // Look for wrangler in package.json
+      const packagePath = path.join(process.cwd(), 'package.json');
+      if (fs.existsSync(packagePath)) {
+        const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+        const wranglerVersion = packageJson.dependencies?.wrangler || packageJson.devDependencies?.wrangler;
+        if (wranglerVersion) {
+          // Extract version from semver range (e.g., "^3.15.0" -> "3.15.0")
+          const cleanVersion = wranglerVersion.replace(/[^\d.]/g, '');
+          if (cleanVersion) {
+            console.log(`📋 Using Wrangler version from package.json: ${cleanVersion}`);
+            return cleanVersion;
+          }
+        }
+      }
+    } catch (error) {
+      console.warn(`⚠️  Fallback detection failed: ${error.message}`);
+    }
+
+    // Default to latest stable version
+    console.log('📋 Using default Wrangler version: 4.0.0');
+    return '4.0.0';
+  }
+
+  /**
+   * Gets optimal Wrangler configuration for the detected version
+   * @param {string} version - Wrangler version
+   * @returns {Object} Optimal configuration object
+   */
+  getOptimalConfig(version) {
+    const majorVersion = parseInt(version.split('.')[0]);
+    if (majorVersion >= 4) {
+      // Wrangler v4+ uses nodejs_compat flag
+      return {
+        nodejs_compat: true
+      };
+    } else if (majorVersion >= 3) {
+      // Wrangler v3 uses compatibility_flags array
+      return {
+        compatibility_flags: ["nodejs_compat"]
+      };
+    } else {
+      // Wrangler v2 and below - minimal compatibility
+      return {
+        compatibility_flags: []
+      };
+    }
+  }
+
+  /**
+   * Gets build configuration optimized for the Wrangler version
+   * @param {string} version - Wrangler version
+   * @returns {Object} Build configuration object
+   */
+  getBuildConfig(version) {
+    const majorVersion = parseInt(version.split('.')[0]);
+    const baseConfig = {
+      command: "npm run build",
+      upload: {
+        format: "modules"
+      }
+    };
+
+    // Add Node.js module externalization for v3+
+    if (majorVersion >= 3) {
+      baseConfig.upload.external = {
+        include: ["node:*"]
+      };
+    }
+    return baseConfig;
+  }
+
+  /**
+   * Validates if current configuration is optimal for the Wrangler version
+   * @param {Object} config - Current Wrangler configuration
+   * @param {string} version - Wrangler version
+   * @returns {Object} Validation result with issues and suggestions
+   */
+  validateConfig(config, version) {
+    const issues = [];
+    const optimalConfig = this.getOptimalConfig(version);
+
+    // Check Node.js compatibility settings
+    if (optimalConfig.nodejs_compat !== undefined) {
+      if (config.nodejs_compat !== optimalConfig.nodejs_compat) {
+        issues.push({
+          type: 'COMPATIBILITY_CONFIG',
+          severity: 'ERROR',
+          message: `nodejs_compat should be ${optimalConfig.nodejs_compat} for Wrangler ${version}`,
+          fix: `Set nodejs_compat = ${optimalConfig.nodejs_compat} in wrangler.toml`
+        });
+      }
+    } else if (optimalConfig.compatibility_flags) {
+      const hasNodejsCompat = config.compatibility_flags?.includes('nodejs_compat');
+      const shouldHaveNodejsCompat = optimalConfig.compatibility_flags.includes('nodejs_compat');
+      if (hasNodejsCompat !== shouldHaveNodejsCompat) {
+        issues.push({
+          type: 'COMPATIBILITY_FLAGS',
+          severity: 'ERROR',
+          message: `compatibility_flags should ${shouldHaveNodejsCompat ? 'include' : 'exclude'} "nodejs_compat" for Wrangler ${version}`,
+          fix: shouldHaveNodejsCompat ? 'Add "nodejs_compat" to compatibility_flags array' : 'Remove "nodejs_compat" from compatibility_flags array'
+        });
+      }
+    }
+    return {
+      isValid: issues.filter(issue => issue.severity === 'ERROR').length === 0,
+      issues
+    };
+  }
+
+  /**
+   * Generates a complete optimized Wrangler configuration
+   * @param {string} version - Wrangler version
+   * @param {Object} baseConfig - Base configuration to extend
+   * @returns {Object} Complete optimized configuration
+   */
+  generateOptimalConfig(version, baseConfig = {}) {
+    const optimalConfig = this.getOptimalConfig(version);
+    const buildConfig = this.getBuildConfig(version);
+    return {
+      ...baseConfig,
+      ...optimalConfig,
+      build: {
+        ...buildConfig,
+        ...(baseConfig.build || {})
+      }
+    };
+  }
+}
+
+// Export singleton instance for convenience
+export const wranglerCompatibility = new WranglerCompatibilityDetector();

package/dist/lib/shared/validation/config-validator.js

@@ -0,0 +1,383 @@
+/**
+ * Configuration Validator
+ *
+ * Validates Wrangler and service configurations before deployment
+ * to prevent common deployment failures and provide actionable feedback.
+ */
+
+import { WranglerCompatibilityDetector } from '../utils/wrangler-compatibility.js';
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Configuration Validation Result
+ * @typedef {Object} ValidationResult
+ * @property {boolean} isValid - Whether configuration is valid
+ * @property {ValidationIssue[]} issues - List of validation issues
+ * @property {string[]} warnings - Non-blocking warnings
+ * @property {string[]} suggestions - Improvement suggestions
+ */
+
+/**
+ * Validation Issue
+ * @typedef {Object} ValidationIssue
+ * @property {string} type - Issue type identifier
+ * @property {string} severity - ERROR, WARNING, or INFO
+ * @property {string} message - Human-readable message
+ * @property {string} fix - Suggested fix
+ * @property {string} [file] - File where issue occurs
+ * @property {number} [line] - Line number if applicable
+ */
+
+/**
+ * Configuration Validator
+ * Handles pre-deployment configuration validation
+ */
+export class ConfigurationValidator {
+  constructor() {
+    this.compatibilityDetector = new WranglerCompatibilityDetector();
+  }
+
+  /**
+   * Validates a complete service configuration
+   * @param {string} servicePath - Path to service directory
+   * @param {Object} options - Validation options
+   * @returns {Promise<ValidationResult>} Validation result
+   */
+  async validateServiceConfig(servicePath, options = {}) {
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    try {
+      // Load wrangler.toml
+      const wranglerConfig = await this.loadWranglerConfig(servicePath);
+      if (!wranglerConfig) {
+        issues.push({
+          type: 'MISSING_CONFIG',
+          severity: 'ERROR',
+          message: 'wrangler.toml not found in service directory',
+          fix: 'Create wrangler.toml file or run service generation'
+        });
+        return {
+          isValid: false,
+          issues,
+          warnings,
+          suggestions
+        };
+      }
+
+      // Detect Wrangler version
+      const wranglerVersion = await this.compatibilityDetector.detectVersion();
+
+      // Validate compatibility settings
+      const compatibilityResult = this.compatibilityDetector.validateConfig(wranglerConfig, wranglerVersion);
+      issues.push(...compatibilityResult.issues);
+
+      // Validate build configuration
+      const buildIssues = this.validateBuildConfig(wranglerConfig);
+      issues.push(...buildIssues);
+
+      // Validate service structure
+      const structureIssues = await this.validateServiceStructure(servicePath);
+      issues.push(...structureIssues);
+
+      // Check for common issues
+      const commonIssues = await this.checkCommonIssues(servicePath, wranglerConfig);
+      warnings.push(...commonIssues.warnings);
+      suggestions.push(...commonIssues.suggestions);
+
+      // Generate improvement suggestions
+      if (options.verbose) {
+        suggestions.push(...this.generateOptimizationSuggestions(wranglerConfig, wranglerVersion));
+      }
+      const isValid = issues.filter(issue => issue.severity === 'ERROR').length === 0;
+      return {
+        isValid,
+        issues,
+        warnings,
+        suggestions
+      };
+    } catch (error) {
+      issues.push({
+        type: 'VALIDATION_ERROR',
+        severity: 'ERROR',
+        message: `Configuration validation failed: ${error.message}`,
+        fix: 'Check service directory structure and configuration files'
+      });
+      return {
+        isValid: false,
+        issues,
+        warnings,
+        suggestions
+      };
+    }
+  }
+
+  /**
+   * Loads and parses wrangler.toml configuration
+   * @param {string} servicePath - Path to service directory
+   * @returns {Promise<Object|null>} Parsed configuration or null if not found
+   */
+  async loadWranglerConfig(servicePath) {
+    const configPath = path.join(servicePath, 'wrangler.toml');
+    try {
+      if (!fs.existsSync(configPath)) {
+        return null;
+      }
+
+      // For now, return a basic parsed config
+      // In a real implementation, you'd use a TOML parser
+      const configContent = fs.readFileSync(configPath, 'utf8');
+
+      // Basic TOML parsing (simplified - would use proper TOML parser in production)
+      return this.parseTomlConfig(configContent);
+    } catch (error) {
+      throw new Error(`Failed to load wrangler.toml: ${error.message}`);
+    }
+  }
+
+  /**
+   * Basic TOML config parser (simplified)
+   * @param {string} content - TOML content
+   * @returns {Object} Parsed configuration
+   */
+  parseTomlConfig(content) {
+    const config = {};
+
+    // Very basic parsing - in production, use a proper TOML library
+    const lines = content.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+
+      // Skip comments and empty lines
+      if (!trimmed || trimmed.startsWith('#')) continue;
+
+      // Parse key = value
+      const equalsIndex = trimmed.indexOf('=');
+      if (equalsIndex > 0) {
+        const key = trimmed.substring(0, equalsIndex).trim();
+        const value = trimmed.substring(equalsIndex + 1).trim();
+
+        // Handle different value types
+        if (value === 'true') {
+          config[key] = true;
+        } else if (value === 'false') {
+          config[key] = false;
+        } else if (value.startsWith('"') && value.endsWith('"')) {
+          config[key] = value.slice(1, -1);
+        } else if (value.startsWith('[') && value.endsWith(']')) {
+          // Basic array parsing
+          const arrayContent = value.slice(1, -1);
+          config[key] = arrayContent.split(',').map(item => item.trim().replace(/"/g, ''));
+        } else {
+          config[key] = value;
+        }
+      }
+    }
+    return config;
+  }
+
+  /**
+   * Validates build configuration
+   * @param {Object} config - Wrangler configuration
+   * @returns {ValidationIssue[]} Build-related issues
+   */
+  validateBuildConfig(config) {
+    const issues = [];
+
+    // Check build command
+    if (!config.build?.command) {
+      issues.push({
+        type: 'MISSING_BUILD_COMMAND',
+        severity: 'WARNING',
+        message: 'Build command not specified',
+        fix: 'Add build.command = "npm run build" to wrangler.toml'
+      });
+    }
+
+    // Check upload format
+    if (config.build?.upload?.format !== 'modules') {
+      issues.push({
+        type: 'BUILD_FORMAT',
+        severity: 'INFO',
+        message: 'Consider using modules format for better performance',
+        fix: 'Set build.upload.format = "modules"'
+      });
+    }
+    return issues;
+  }
+
+  /**
+   * Validates service directory structure
+   * @param {string} servicePath - Path to service directory
+   * @returns {Promise<ValidationIssue[]>} Structure-related issues
+   */
+  async validateServiceStructure(servicePath) {
+    const issues = [];
+
+    // Check for package.json
+    const packagePath = path.join(servicePath, 'package.json');
+    if (!fs.existsSync(packagePath)) {
+      issues.push({
+        type: 'MISSING_PACKAGE_JSON',
+        severity: 'ERROR',
+        message: 'package.json not found',
+        fix: 'Create package.json with service dependencies'
+      });
+    }
+
+    // Check for src directory
+    const srcPath = path.join(servicePath, 'src');
+    if (!fs.existsSync(srcPath)) {
+      issues.push({
+        type: 'MISSING_SRC_DIR',
+        severity: 'WARNING',
+        message: 'src directory not found',
+        fix: 'Create src directory with service code'
+      });
+    }
+    return issues;
+  }
+
+  /**
+   * Checks for common configuration issues
+   * @param {string} servicePath - Path to service directory
+   * @param {Object} config - Wrangler configuration
+   * @returns {Object} Common issues with warnings and suggestions
+   */
+  async checkCommonIssues(servicePath, config) {
+    const warnings = [];
+    const suggestions = [];
+
+    // Check for large bundle potential
+    if (!config.build?.upload?.external?.include?.includes('node:*')) {
+      warnings.push('Consider externalizing Node.js modules to reduce bundle size');
+    }
+
+    // Check for missing environment variables
+    if (config.vars) {
+      const varKeys = Object.keys(config.vars);
+      suggestions.push(`Consider moving ${varKeys.length} environment variables to .env file for security`);
+    }
+    return {
+      warnings,
+      suggestions
+    };
+  }
+
+  /**
+   * Generates optimization suggestions
+   * @param {Object} config - Current configuration
+   * @param {string} wranglerVersion - Wrangler version
+   * @returns {string[]} Optimization suggestions
+   */
+  generateOptimizationSuggestions(config, wranglerVersion) {
+    const suggestions = [];
+
+    // Performance suggestions
+    if (!config.build?.minify) {
+      suggestions.push('Enable minification: build.minify = true');
+    }
+
+    // Security suggestions
+    if (!config.build?.upload?.external) {
+      suggestions.push('Externalize dependencies to reduce bundle size and improve cold start performance');
+    }
+    return suggestions;
+  }
+
+  /**
+   * Fixes common configuration issues automatically
+   * @param {string} servicePath - Path to service directory
+   * @param {ValidationResult} validationResult - Validation result
+   * @returns {Promise<Object>} Fix result
+   */
+  async autoFix(servicePath, validationResult) {
+    const fixes = [];
+    const errors = [];
+    try {
+      const wranglerVersion = await this.compatibilityDetector.detectVersion();
+      const currentConfig = await this.loadWranglerConfig(servicePath);
+      if (!currentConfig) {
+        errors.push('Cannot auto-fix: wrangler.toml not found');
+        return {
+          success: false,
+          fixes,
+          errors
+        };
+      }
+
+      // Generate optimal config
+      const optimalConfig = this.compatibilityDetector.generateOptimalConfig(wranglerVersion, currentConfig);
+
+      // Apply fixes for auto-fixable issues
+      for (const issue of validationResult.issues) {
+        if (issue.type === 'COMPATIBILITY_CONFIG' && optimalConfig.nodejs_compat !== undefined) {
+          optimalConfig.nodejs_compat = optimalConfig.nodejs_compat;
+          fixes.push('Fixed nodejs_compat setting');
+        } else if (issue.type === 'COMPATIBILITY_FLAGS') {
+          optimalConfig.compatibility_flags = optimalConfig.compatibility_flags;
+          fixes.push('Fixed compatibility_flags setting');
+        }
+      }
+
+      // Save updated config
+      await this.saveWranglerConfig(servicePath, optimalConfig);
+      fixes.push('Updated wrangler.toml with optimal configuration');
+      return {
+        success: true,
+        fixes,
+        errors
+      };
+    } catch (error) {
+      errors.push(`Auto-fix failed: ${error.message}`);
+      return {
+        success: false,
+        fixes,
+        errors
+      };
+    }
+  }
+
+  /**
+   * Saves wrangler configuration to file
+   * @param {string} servicePath - Path to service directory
+   * @param {Object} config - Configuration to save
+   */
+  async saveWranglerConfig(servicePath, config) {
+    const configPath = path.join(servicePath, 'wrangler.toml');
+
+    // Basic TOML generation (simplified - would use proper TOML library in production)
+    let tomlContent = '# Auto-generated by Clodo Framework\n\n';
+
+    // Add main config
+    if (config.name) tomlContent += `name = "${config.name}"\n`;
+    if (config.main) tomlContent += `main = "${config.main}"\n`;
+    if (config.compatibility_flags) {
+      tomlContent += `compatibility_flags = ${JSON.stringify(config.compatibility_flags)}\n`;
+    }
+    if (config.nodejs_compat !== undefined) {
+      tomlContent += `nodejs_compat = ${config.nodejs_compat}\n`;
+    }
+
+    // Add build config
+    if (config.build) {
+      tomlContent += '\n[build]\n';
+      if (config.build.command) tomlContent += `command = "${config.build.command}"\n`;
+      if (config.build.upload) {
+        tomlContent += '\n[build.upload]\n';
+        if (config.build.upload.format) tomlContent += `format = "${config.build.upload.format}"\n`;
+        if (config.build.upload.external) {
+          tomlContent += '\n[build.upload.external]\n';
+          if (config.build.upload.external.include) {
+            tomlContent += `include = ${JSON.stringify(config.build.upload.external.include)}\n`;
+          }
+        }
+      }
+    }
+    fs.writeFileSync(configPath, tomlContent, 'utf8');
+  }
+}
+
+// Export singleton instance
+export const configValidator = new ConfigurationValidator();

package/dist/service-management/generators/config/WranglerTomlGenerator.js

@@ -1,4 +1,5 @@
 import { BaseGenerator } from '../BaseGenerator.js';
+import { WranglerCompatibilityDetector } from '../../../../lib/shared/utils/wrangler-compatibility.js';
 import { join } from 'path';
 
 /**
@@ -58,7 +59,7 @@ export class WranglerTomlGenerator extends BaseGenerator {
     const siteConfig = await this._generateSiteConfig(coreInputs);
 
     // Build wrangler.toml content
-    const content = this._buildWranglerToml(coreInputs, confirmedValues, routesConfig, siteConfig);
+    const content = await this._buildWranglerToml(coreInputs, confirmedValues, routesConfig, siteConfig);
 
     // Write file
     await this.writeFile('wrangler.toml', content);
@@ -115,13 +116,42 @@ export class WranglerTomlGenerator extends BaseGenerator {
   /**
    * Build the complete wrangler.toml content
    */
-  _buildWranglerToml(coreInputs, confirmedValues, routesConfig, siteConfig) {
+  async _buildWranglerToml(coreInputs, confirmedValues, routesConfig, siteConfig) {
     const compatDate = new Date().toISOString().split('T')[0];
+
+    // Detect Wrangler version and get optimal compatibility config
+    let compatibilityString = 'compatibility_flags = ["nodejs_compat"]';
+    let buildString = '\n\n[build]\ncommand = "npm run build"\n\n[build.upload]\nformat = "modules"\n\n[build.upload.external]\ninclude = ["node:*"]';
+    try {
+      const compatibilityDetector = new WranglerCompatibilityDetector();
+      const wranglerVersion = await Promise.race([compatibilityDetector.detectVersion(), new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), 2000)) // 2 second timeout
+      ]);
+      const compatibilityConfig = compatibilityDetector.getOptimalConfig(wranglerVersion);
+      const buildConfig = compatibilityDetector.getBuildConfig(wranglerVersion);
+
+      // Build compatibility flags string
+      if (compatibilityConfig.nodejs_compat !== undefined) {
+        compatibilityString = `nodejs_compat = ${compatibilityConfig.nodejs_compat}`;
+      } else if (compatibilityConfig.compatibility_flags) {
+        compatibilityString = `compatibility_flags = ${JSON.stringify(compatibilityConfig.compatibility_flags)}`;
+      }
+
+      // Add any additional build config from detector (if needed)
+      if (buildConfig.command && buildConfig.command !== "npm run build") {
+        buildString += `\n\n# Additional build config from Wrangler ${wranglerVersion}\n[build.v${wranglerVersion.split('.')[0]}]\ncommand = "${buildConfig.command}"`;
+      }
+      if (buildConfig.upload && buildConfig.upload.format && buildConfig.upload.format !== "modules") {
+        buildString += `\nformat_override = "${buildConfig.upload.format}"`;
+      }
+    } catch (error) {
+      // Fall back to default configuration if detection fails
+      console.warn(`⚠️  Wrangler compatibility detection failed, using defaults: ${error.message}`);
+    }
     return `# Cloudflare Workers Configuration for ${confirmedValues.displayName}
 name = "${confirmedValues.workerName}"
 main = "src/worker/index.js"
 compatibility_date = "${compatDate}"
-compatibility_flags = ["nodejs_compat"]
+${compatibilityString}${buildString}
 
 # Account configuration
 account_id = "${coreInputs.cloudflareAccountId}"

package/dist/service-management/handlers/ValidationHandler.js

@@ -6,6 +6,8 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { FrameworkConfig } from '../../utils/framework-config.js';
+// import { ConfigurationValidator } from '../../lib/shared/utils/configuration-validator.js';
+
 export class ValidationHandler {
   constructor(options = {}) {
     this.strict = options.strict || false;
@@ -90,6 +92,19 @@ export class ValidationHandler {
     // Validate wrangler configuration
     const wranglerValidation = await this.validateWranglerConfig(servicePath);
     issues.push(...wranglerValidation.issues);
+
+    // Run comprehensive configuration validation using ConfigurationValidator
+    // Temporarily disabled due to import issues
+    // try {
+    //   const configValidation = await ConfigurationValidator.validateServiceConfig(servicePath);
+    //   if (!configValidation.isValid) {
+    //     issues.push(...configValidation.errors);
+    //     issues.push(...configValidation.warnings.map(w => `Warning: ${w}`));
+    //   }
+    // } catch (error) {
+    //   issues.push(`Configuration validation failed: ${error.message}`);
+    // }
+
     return {
       valid: issues.length === 0,
       issues,

package/dist/utils/file-manager.js

@@ -3,18 +3,11 @@
  * 
  * Re-exports FileManager from lib/ for library use.
  * 
- * IMPORTANT PATH CALCULATION FOR NPM PACKAGE:
- * - Source: src/utils/file-manager.js (2 levels from root)
- * - Compiled: dist/utils/file-manager.js (2 levels from root)
- * 
- * When installed via npm, structure is:
- *   node_modules/@tamyla/clodo-framework/
- *     dist/
- *       utils/file-manager.js
- *       lib/shared/utils/file-manager.js
- * 
- * From dist/utils/, need to go UP one level (../) to reach lib/
- * Source path must account for compilation depth adjustment
+ * IMPORTANT PATH CALCULATION:
+ * - Source: src/utils/file-manager.js
+ * - Compiled: dist/utils/file-manager.js
+ * - Target: dist/lib/shared/utils/file-manager.js
+ * - From dist/utils/, path to dist/lib/ is ../lib/
  */
 
 export { FileManager } from '../lib/shared/utils/file-manager.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tamyla/clodo-framework",
-  "version": "4.0.11",
+  "version": "4.0.12",
   "description": "Reusable framework for Clodo-style software architecture on Cloudflare Workers + D1",
   "type": "module",
   "sideEffects": [