@tamyla/clodo-framework 4.0.14 → 4.1.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [4.1.0](https://github.com/tamylaa/clodo-framework/compare/v4.0.15...v4.1.0) (2026-01-31)
+
+
+### Bug Fixes
+
+* **lint:** remove unnecessary escape in serviceName regex to satisfy no-useless-escape ([ac4dcda](https://github.com/tamylaa/clodo-framework/commit/ac4dcdabb39dda3dba3f4e06022f28936a53d645))
+
+
+### Features
+
+* **programmatic-service-api:** programmatic createService + configurable validation ([#4](https://github.com/tamylaa/clodo-framework/issues/4)) ([040f68b](https://github.com/tamylaa/clodo-framework/commit/040f68b9115b604b3f27d7baa14c63122494c5f3))
+
+## [4.0.15](https://github.com/tamylaa/clodo-framework/compare/v4.0.14...v4.0.15) (2026-01-31)
+
+
+### Bug Fixes
+
+* **lint:** remove unnecessary escape in semver regex ([72751bd](https://github.com/tamylaa/clodo-framework/commit/72751bdf9a98b2f6b1f97706b175ea31f3aa0df1))
+
 ## [4.0.14](https://github.com/tamylaa/clodo-framework/compare/v4.0.13...v4.0.14) (2026-01-19)
 
 

package/dist/config/service-schema-config.js

@@ -0,0 +1,22 @@
+// Centralized configuration for service payload schema values
+// Allows runtime overrides for enums and features to keep validation flexible and configurable
+
+let config = {
+  serviceTypes: ['api-service', 'data-service', 'worker', 'pages', 'gateway', 'generic'],
+  features: ['d1', 'upstash', 'r2', 'pages', 'ws', 'durableObject', 'cron', 'metrics']
+};
+export function getConfig() {
+  return {
+    ...config
+  };
+}
+export function setConfig(updates = {}) {
+  if (updates.serviceTypes) config.serviceTypes = [...updates.serviceTypes];
+  if (updates.features) config.features = [...updates.features];
+}
+export function resetConfig() {
+  config = {
+    serviceTypes: ['api-service', 'data-service', 'worker', 'pages', 'gateway', 'generic'],
+    features: ['d1', 'upstash', 'r2', 'pages', 'ws', 'durableObject', 'cron', 'metrics']
+  };
+}

package/dist/index.js

@@ -21,6 +21,7 @@ export * from './schema/SchemaManager.js';
 export * from './modules/ModuleManager.js';
 export * from './routing/EnhancedRouter.js';
 export * from './handlers/GenericRouteHandler.js';
+export { ServiceClient } from './services/ServiceClient.js';
 
 // Deployment components
 export { DeploymentValidator } from './deployment/validator.js';
@@ -32,6 +33,7 @@ export { DeploymentAuditor } from './deployment/auditor.js';
 export { SecurityCLI } from './security/SecurityCLI.js';
 export { ConfigurationValidator } from './security/ConfigurationValidator.js';
 export { SecretGenerator } from './security/SecretGenerator.js';
+export { EnvironmentValidator } from './utils/EnvironmentValidator.js';
 
 // Service management components
 export { ServiceCreator } from './service-management/ServiceCreator.js';
@@ -48,6 +50,9 @@ export { verifyWorkerDeployment, healthCheckWithBackoff, checkHealth } from './l
 export { classifyError, getRecoverySuggestions } from './lib/shared/error-handling/error-classifier.js';
 
 // Framework version info
+export { FrameworkInfo } from './version/FrameworkInfo.js';
+export { TemplateRuntime } from './utils/TemplateRuntime.js';
+export { HealthChecker } from './monitoring/HealthChecker.js';
 export const FRAMEWORK_VERSION = '1.0.0';
 export const FRAMEWORK_NAME = 'Clodo Framework';
 

package/dist/monitoring/HealthChecker.js

@@ -0,0 +1,286 @@
+/**
+ * Runtime Health Checker
+ * Provides health validation and monitoring for services
+ */
+
+/**
+ * Runtime Health Checker for service monitoring
+ */
+export class HealthChecker {
+  constructor(options = {}) {
+    this.options = {
+      timeout: options.timeout || 5000,
+      interval: options.interval || 30000,
+      retries: options.retries || 2,
+      ...options
+    };
+    this.checks = new Map();
+    this.lastCheck = null;
+    this.overallStatus = 'unknown';
+  }
+
+  /**
+   * Add a health check
+   * @param {string} name - Check name
+   * @param {Function} checkFunction - Async function that returns health status
+   * @param {Object} options - Check options
+   */
+  addCheck(name, checkFunction, options = {}) {
+    this.checks.set(name, {
+      name,
+      checkFunction,
+      options: {
+        timeout: options.timeout || this.options.timeout,
+        critical: options.critical !== false,
+        ...options
+      },
+      lastResult: null,
+      lastCheck: null
+    });
+  }
+
+  /**
+   * Remove a health check
+   * @param {string} name - Check name
+   */
+  removeCheck(name) {
+    this.checks.delete(name);
+  }
+
+  /**
+   * Run all health checks
+   * @returns {Promise<Object>} Health status
+   */
+  async runChecks() {
+    const results = {
+      status: 'healthy',
+      timestamp: new Date().toISOString(),
+      checks: {},
+      summary: {
+        total: this.checks.size,
+        healthy: 0,
+        unhealthy: 0,
+        unknown: 0
+      }
+    };
+    const checkPromises = Array.from(this.checks.entries()).map(async ([name, check]) => {
+      try {
+        const startTime = Date.now();
+        const result = await this.runSingleCheck(check);
+        const duration = Date.now() - startTime;
+        results.checks[name] = {
+          status: result.status,
+          duration,
+          timestamp: new Date().toISOString(),
+          ...result.details
+        };
+
+        // Update summary
+        results.summary[result.status === 'healthy' ? 'healthy' : 'unhealthy']++;
+
+        // Update overall status
+        if (result.status !== 'healthy' && check.options.critical) {
+          results.status = 'unhealthy';
+        }
+      } catch (error) {
+        results.checks[name] = {
+          status: 'unhealthy',
+          error: error.message,
+          timestamp: new Date().toISOString()
+        };
+        results.summary.unhealthy++;
+        if (check.options.critical) {
+          results.status = 'unhealthy';
+        }
+      }
+    });
+    await Promise.all(checkPromises);
+    this.lastCheck = results;
+    return results;
+  }
+
+  /**
+   * Run a single health check with timeout and retries
+   * @param {Object} check - Check configuration
+   * @returns {Promise<Object>} Check result
+   */
+  async runSingleCheck(check) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.options.retries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), check.options.timeout);
+        const result = await check.checkFunction({
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        check.lastResult = result;
+        check.lastCheck = new Date();
+        return {
+          status: 'healthy',
+          details: result
+        };
+      } catch (error) {
+        lastError = error;
+        if (attempt === this.options.retries) {
+          break;
+        }
+
+        // Wait before retry
+        await this.sleep(1000 * attempt);
+      }
+    }
+    throw lastError;
+  }
+
+  /**
+   * Get the last health check results
+   * @returns {Object|null} Last check results
+   */
+  getLastResults() {
+    return this.lastCheck;
+  }
+
+  /**
+   * Get overall health status
+   * @returns {string} Health status
+   */
+  getStatus() {
+    return this.lastCheck?.status || 'unknown';
+  }
+
+  /**
+   * Check if service is healthy
+   * @returns {boolean} True if healthy
+   */
+  isHealthy() {
+    return this.getStatus() === 'healthy';
+  }
+
+  /**
+   * Add common health checks
+   * @param {Object} env - Cloudflare Worker environment
+   */
+  addCommonChecks(env) {
+    // Database connectivity check
+    if (env.DATABASE) {
+      this.addCheck('database', async () => {
+        await env.DATABASE.prepare('SELECT 1').first();
+        return {
+          message: 'Database connection successful'
+        };
+      });
+    }
+
+    // KV connectivity check
+    if (env.KV_CACHE) {
+      this.addCheck('kv', async () => {
+        await env.KV_CACHE.put('health-check', 'ok', {
+          expirationTtl: 60
+        });
+        return {
+          message: 'KV connection successful'
+        };
+      });
+    }
+
+    // R2 connectivity check
+    if (env.R2_STORAGE) {
+      this.addCheck('r2', async () => {
+        // Try to list objects (will work if bucket exists and is accessible)
+        try {
+          const objects = await env.R2_STORAGE.list({
+            limit: 1
+          });
+          return {
+            message: 'R2 connection successful'
+          };
+        } catch (error) {
+          // If list fails, try a simple head request on a test object
+          await env.R2_STORAGE.head('health-check-test');
+          return {
+            message: 'R2 connection successful'
+          };
+        }
+      });
+    }
+
+    // Memory usage check
+    this.addCheck('memory', async () => {
+      // In Cloudflare Workers, memory is managed automatically
+      // This is just a placeholder for custom memory checks
+      return {
+        message: 'Memory check passed'
+      };
+    }, {
+      critical: false
+    });
+  }
+
+  /**
+   * Start periodic health checking
+   * @param {Object} env - Cloudflare Worker environment
+   */
+  startPeriodicChecks(env) {
+    // Add common checks if not already added
+    if (this.checks.size === 0) {
+      this.addCommonChecks(env);
+    }
+
+    // Run initial check
+    this.runChecks().catch(error => {
+      console.error('Initial health check failed:', error);
+    });
+
+    // Set up periodic checks
+    if (this.options.interval > 0) {
+      this.intervalId = setInterval(async () => {
+        try {
+          await this.runChecks();
+        } catch (error) {
+          console.error('Periodic health check failed:', error);
+        }
+      }, this.options.interval);
+    }
+  }
+
+  /**
+   * Stop periodic health checking
+   */
+  stopPeriodicChecks() {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+
+  /**
+   * Get health check summary
+   * @returns {Object} Summary of health status
+   */
+  getSummary() {
+    if (!this.lastCheck) {
+      return {
+        status: 'unknown',
+        message: 'No health checks run yet'
+      };
+    }
+    const summary = {
+      status: this.lastCheck.status,
+      timestamp: this.lastCheck.timestamp,
+      totalChecks: this.lastCheck.summary.total,
+      healthyChecks: this.lastCheck.summary.healthy,
+      unhealthyChecks: this.lastCheck.summary.unhealthy
+    };
+    return summary;
+  }
+
+  /**
+   * Sleep utility
+   * @param {number} ms - Milliseconds to sleep
+   * @returns {Promise<void>}
+   */
+  sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}

package/dist/orchestration/modules/StateManager.js

@@ -11,8 +11,11 @@ export class StateManager {
   constructor(options = {}) {
     this.environment = options.environment || 'production';
     this.dryRun = options.dryRun || false;
-    this.logDirectory = options.logDirectory || 'deployments';
-    this.enablePersistence = options.enablePersistence !== false;
+    // Default to ephemeral cache directory to avoid polluting workspace root with artifacts
+    this.logDirectory = options.logDirectory || '.clodo-cache/deployments';
+    // Persistence must be explicitly enabled via options or environment variable to avoid
+    // accidentally creating deployment artifacts in developer workspaces.
+    this.enablePersistence = options.enablePersistence ?? process.env.CLODO_ENABLE_PERSISTENCE === '1';
     this.rollbackEnabled = options.rollbackEnabled !== false;
 
     // Initialize portfolio state
@@ -258,7 +261,12 @@ export class StateManager {
    * @returns {Promise<void>}
    */
   async saveAuditLog() {
-    if (!this.enablePersistence) return;
+    // Respect persistence opt-in: do not write orchestration artifacts unless enabled
+    if (!this.enablePersistence) {
+      // Avoid creating files during tests or normal developer runs
+      if (this.verbose) console.log('   ℹ️ Persistence disabled: skipping saveAuditLog');
+      return;
+    }
     try {
       // Ensure log directory exists
       try {

package/dist/programmatic/createService.js

@@ -0,0 +1,9 @@
+import { ServiceOrchestrator } from '../service-management/ServiceOrchestrator.js';
+export async function createServiceProgrammatic(payload, options = {}) {
+  const orchestrator = new ServiceOrchestrator({
+    interactive: false,
+    outputPath: options.outputDir || '.'
+  });
+  return await orchestrator.createService(payload, options);
+}
+export const createService = createServiceProgrammatic; // Backwards-compatible alias

package/dist/security/ConfigurationValidator.js

@@ -460,6 +460,222 @@ export class ConfigurationValidator {
     return config;
   }
 
+  /**
+   * Validate service configuration consistency between manifest and wrangler config
+   * @param {string} manifestPath - Path to manifest.json
+   * @param {string} wranglerPath - Path to wrangler.toml
+   * @returns {Object} Validation result with issues array
+   */
+  static validateServiceConfig(manifestPath, wranglerPath) {
+    const issues = [];
+    try {
+      // Read manifest.json
+      const manifestContent = readFileSync(manifestPath, 'utf8');
+      const manifest = JSON.parse(manifestContent);
+
+      // Read wrangler.toml (basic parsing - could be enhanced with a TOML parser)
+      const wranglerContent = readFileSync(wranglerPath, 'utf8');
+      const wranglerConfig = this.parseWranglerToml(wranglerContent);
+
+      // Validate D1 database consistency
+      this.validateD1Consistency(manifest, wranglerConfig, issues);
+
+      // Validate KV namespace consistency
+      this.validateKVConsistency(manifest, wranglerConfig, issues);
+
+      // Validate R2 bucket consistency
+      this.validateR2Consistency(manifest, wranglerConfig, issues);
+
+      // Validate environment variables
+      this.validateEnvironmentConsistency(manifest, wranglerConfig, issues);
+    } catch (error) {
+      issues.push({
+        type: 'error',
+        message: `Configuration validation failed: ${error.message}`,
+        severity: 'critical'
+      });
+    }
+    return {
+      valid: issues.length === 0,
+      issues: issues
+    };
+  }
+
+  /**
+   * Parse wrangler.toml content (basic implementation)
+   * @param {string} content - TOML content
+   * @returns {Object} Parsed configuration
+   */
+  static parseWranglerToml(content) {
+    const config = {
+      d1_databases: [],
+      kv_namespaces: [],
+      r2_buckets: [],
+      vars: {}
+    };
+    if (!content || !content.trim()) {
+      return config;
+    }
+    const lines = content.split('\n');
+    let currentSection = null;
+    for (const line of lines) {
+      const trimmed = line.trim();
+
+      // Section headers
+      if (trimmed.startsWith('[[')) {
+        if (trimmed.includes('d1_databases')) {
+          currentSection = 'd1_databases';
+          config.d1_databases.push({});
+        } else if (trimmed.includes('kv_namespaces')) {
+          currentSection = 'kv_namespaces';
+          config.kv_namespaces.push({});
+        } else if (trimmed.includes('r2_buckets')) {
+          currentSection = 'r2_buckets';
+          config.r2_buckets.push({});
+        }
+      } else if (trimmed.startsWith('[') && !trimmed.startsWith('[[')) {
+        currentSection = trimmed.replace(/\[|\]/g, '');
+        // Support both table and array-of-tables syntaxes by creating a container
+        if (Array.isArray(config[currentSection]) && config[currentSection].length === 0) {
+          config[currentSection].push({});
+        }
+      }
+      // Key-value pairs
+      else if (trimmed.includes('=') && currentSection) {
+        const [key, ...valueParts] = trimmed.split('=');
+        const value = valueParts.join('=').trim().replace(/"/g, '');
+        if (currentSection === 'vars') {
+          config.vars[key.trim()] = value;
+        } else if (Array.isArray(config[currentSection])) {
+          const currentItem = config[currentSection][config[currentSection].length - 1];
+          if (currentItem) {
+            currentItem[key.trim()] = value;
+          }
+        }
+      }
+    }
+    return config;
+  }
+
+  /**
+   * Validate D1 database consistency
+   */
+  static validateD1Consistency(manifest, wranglerConfig, issues) {
+    const manifestD1 = manifest.d1 || false;
+    const wranglerD1 = wranglerConfig.d1_databases || [];
+    if (manifestD1 === true && wranglerD1.length === 0) {
+      issues.push({
+        type: 'mismatch',
+        message: 'Manifest declares D1=true but wrangler.toml has no [[d1_databases]] configured',
+        severity: 'critical',
+        manifest: {
+          d1: manifestD1
+        },
+        wrangler: {
+          d1_databases: wranglerD1
+        }
+      });
+    } else if (manifestD1 === false && wranglerD1.length > 0) {
+      issues.push({
+        type: 'mismatch',
+        message: 'Manifest declares D1=false but wrangler.toml has [[d1_databases]] configured',
+        severity: 'critical',
+        manifest: {
+          d1: manifestD1
+        },
+        wrangler: {
+          d1_databases: wranglerD1
+        }
+      });
+    }
+  }
+
+  /**
+   * Validate KV namespace consistency
+   */
+  static validateKVConsistency(manifest, wranglerConfig, issues) {
+    const manifestKV = manifest.kv || false;
+    const wranglerKV = wranglerConfig.kv_namespaces || [];
+    if (manifestKV === true && wranglerKV.length === 0) {
+      issues.push({
+        type: 'mismatch',
+        message: 'Manifest declares KV=true but wrangler.toml has no [[kv_namespaces]] configured',
+        severity: 'critical',
+        manifest: {
+          kv: manifestKV
+        },
+        wrangler: {
+          kv_namespaces: wranglerKV
+        }
+      });
+    } else if (manifestKV === false && wranglerKV.length > 0) {
+      issues.push({
+        type: 'mismatch',
+        message: 'Manifest declares KV=false but wrangler.toml has [[kv_namespaces]] configured',
+        severity: 'critical',
+        manifest: {
+          kv: manifestKV
+        },
+        wrangler: {
+          kv_namespaces: wranglerKV
+        }
+      });
+    }
+  }
+
+  /**
+   * Validate R2 bucket consistency
+   */
+  static validateR2Consistency(manifest, wranglerConfig, issues) {
+    const manifestR2 = manifest.r2 || false;
+    const wranglerR2 = wranglerConfig.r2_buckets || [];
+    if (manifestR2 === true && wranglerR2.length === 0) {
+      issues.push({
+        type: 'mismatch',
+        message: 'Manifest declares R2=true but wrangler.toml has no [[r2_buckets]] configured',
+        severity: 'critical',
+        manifest: {
+          r2: manifestR2
+        },
+        wrangler: {
+          r2_buckets: wranglerR2
+        }
+      });
+    } else if (manifestR2 === false && wranglerR2.length > 0) {
+      issues.push({
+        type: 'mismatch',
+        message: 'Manifest declares R2=false but wrangler.toml has [[r2_buckets]] configured',
+        severity: 'critical',
+        manifest: {
+          r2: manifestR2
+        },
+        wrangler: {
+          r2_buckets: wranglerR2
+        }
+      });
+    }
+  }
+
+  /**
+   * Validate environment variable consistency
+   */
+  static validateEnvironmentConsistency(manifest, wranglerConfig, issues) {
+    const manifestEnv = manifest.environment || {};
+    const wranglerEnv = wranglerConfig.vars || {};
+
+    // Check for required environment variables declared in manifest but missing in wrangler
+    for (const [key, value] of Object.entries(manifestEnv)) {
+      if (value === 'required' && !(key in wranglerEnv)) {
+        issues.push({
+          type: 'missing_env',
+          message: `Manifest declares ${key} as required but not found in wrangler.toml vars`,
+          severity: 'warning',
+          key: key
+        });
+      }
+    }
+  }
+
   /**
    * Log validation results
    */

package/dist/service-management/ServiceOrchestrator.js

@@ -99,6 +99,54 @@ export class ServiceOrchestrator {
     }
   }
 
+  /**
+   * Programmatic service creation API
+   * Accepts a ServicePayload and performs validation, generation and returns structured result
+   */
+  async createService(payload, options = {}) {
+    // Validate payload using new validator
+    const {
+      validateServicePayload
+    } = await import('../validation/payloadValidation.js');
+    const validation = validateServicePayload(payload);
+    if (!validation.valid && !options.force) {
+      return {
+        success: false,
+        errors: validation.errors,
+        warnings: validation.warnings || []
+      };
+    }
+
+    // Map payload to coreInputs expected by generation handlers
+    const coreInputs = {
+      serviceName: payload.serviceName,
+      serviceType: payload.serviceType,
+      domainName: payload.domain,
+      environment: options.environment || 'development'
+    };
+    try {
+      // Generate derived confirmations and run generation
+      const confirmedValues = await this.confirmationHandler.generateAndConfirm(coreInputs);
+      const generationResult = await this.generationHandler.generateService(coreInputs, confirmedValues, {
+        outputPath: options.outputDir || this.outputPath,
+        middlewareStrategy: this.middlewareStrategy
+      });
+      return {
+        success: true,
+        serviceId: generationResult.serviceId || null,
+        servicePath: generationResult.servicePath || null,
+        serviceName: generationResult.serviceName || coreInputs.serviceName,
+        fileCount: generationResult.fileCount || (generationResult.generatedFiles || []).length,
+        generatedFiles: generationResult.generatedFiles || [],
+        warnings: validation.warnings || []
+      };
+    } catch (error) {
+      return {
+        success: false,
+        errors: [error.message]
+      };
+    }
+  }
   /**
    * Validate an existing service configuration
    */