@tamyla/clodo-framework 4.0.13 → 4.0.15

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [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)
+
+
+### Bug Fixes
+
+* middleware packaging, generators, tests, and packaged-artifact smoke test ([b001434](https://github.com/tamylaa/clodo-framework/commit/b001434697da2145e8778b5c0afd02275cd1604e))
+* resolve Windows filesystem timing issues in tests ([7092ca6](https://github.com/tamylaa/clodo-framework/commit/7092ca6ffc230a19d25c96333c0313ead1739f15))
+
 ## [4.0.13](https://github.com/tamylaa/clodo-framework/compare/v4.0.12...v4.0.13) (2025-12-17)
 
 
@@ -173,6 +188,9 @@ Benefits:
   - Moved 13 root-level documentation files to appropriate i-docs categories
   - Root directory now contains only essential project files (config, package.json, README, etc.)
 
+* **Documentation**: Added `docs/HOWTO_CONSUME_CLODO_FRAMEWORK.md` — a concise consumer guide covering CLI usage, public exports, packaging troubleshooting, and recommended consumption patterns.
+* **Middleware Architecture**: Introduce contract-first middleware generation (v4.1 candidate) with `MiddlewareRegistry` and `MiddlewareComposer` to reduce duplication and improve testability. Added a migration tool `scripts/migration/migrate-middleware-legacy-to-contract.js` and a `--middleware-strategy` CLI flag to opt into `legacy` generator output.
+
 * **Configuration Management**: Eliminated hard-coded values from source code
   - Moved domain defaults from ServiceCreator to `validation-config.json`
   - Added configuration hierarchy: CLI option → config file → fallback default

package/README.md

@@ -199,6 +199,13 @@ import { CloudflareAPI } from '@tamyla/clodo-framework/utils/cloudflare';
 
 If you need functionality that's currently only in `bin/`, please open an issue - we'll consider adding it to the public API.
 
+---
+
+## How to consume (quick)
+A short guide and best practices for consuming `@tamyla/clodo-framework` are available in the docs: [docs/HOWTO_CONSUME_CLODO_FRAMEWORK.md](./docs/HOWTO_CONSUME_CLODO_FRAMEWORK.md). This file includes quickstart steps, public export guidance, CLI usage, and troubleshooting tips for packaged artifacts.
+
+If you'd like this information added to `clodo.dev`, I can prepare a small website PR as well.
+
 ## Project Structure
 
 The project is organized for maximum clarity and maintainability:

package/dist/cli/commands/create.js

@@ -9,7 +9,7 @@ import chalk from 'chalk';
 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');
+  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('--middleware-strategy <strategy>', 'Middleware generation strategy: contract|legacy', 'contract').option('--force', 'Skip confirmation prompts').option('--validate', 'Validate service after creation');
 
   // Add standard options (--verbose, --quiet, --json, --no-color, --config-file)
   StandardOptions.define(command).action(async options => {
@@ -40,6 +40,7 @@ export function registerCreateCommand(program) {
         domain: mergedOptions.domainName,
         environment: mergedOptions.environment,
         outputPath: mergedOptions.outputPath,
+        middlewareStrategy: mergedOptions.middlewareStrategy,
         interactive: !mergedOptions.nonInteractive,
         credentials: {
           token: mergedOptions.cloudflareToken,

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/middleware/Composer.js

@@ -0,0 +1,38 @@
+// Middleware composer that runs middleware in sequence and supports short-circuiting
+export class MiddlewareComposer {
+  static compose(...middlewares) {
+    const chain = middlewares.filter(Boolean);
+    return {
+      async execute(request, handler) {
+        // Preprocess/auth/validate phases
+        for (const m of chain) {
+          if (typeof m.preprocess === 'function') {
+            const res = await m.preprocess(request);
+            if (res) return res;
+          }
+          if (typeof m.authenticate === 'function') {
+            const res = await m.authenticate(request);
+            if (res) return res;
+          }
+          if (typeof m.validate === 'function') {
+            const res = await m.validate(request);
+            if (res) return res;
+          }
+        }
+
+        // Call the final handler
+        let response = await handler(request);
+
+        // Postprocess in reverse order
+        for (const m of chain.slice().reverse()) {
+          if (typeof m.postprocess === 'function') {
+            const updated = await m.postprocess(response);
+            // Allow middleware to replace response
+            if (updated instanceof Response) response = updated;
+          }
+        }
+        return response;
+      }
+    };
+  }
+}

package/dist/middleware/Registry.js

@@ -0,0 +1,14 @@
+// Registry for service-specific middleware implementations
+export class MiddlewareRegistry {
+  static implementations = new Map();
+  static register(serviceName, middleware) {
+    if (!serviceName) throw new Error('serviceName is required');
+    this.implementations.set(serviceName, middleware);
+  }
+  static get(serviceName) {
+    return this.implementations.get(serviceName) || null;
+  }
+  static clear() {
+    this.implementations.clear();
+  }
+}

package/dist/middleware/index.js

@@ -0,0 +1,3 @@
+export { MiddlewareRegistry } from './Registry.js';
+export { MiddlewareComposer } from './Composer.js';
+export * as Shared from './shared/index.js';

package/dist/middleware/shared/basicAuth.js

@@ -0,0 +1,21 @@
+export function basicAuth({
+  realm = 'Restricted'
+} = {}) {
+  return {
+    authenticate(request) {
+      const auth = request.headers.get('Authorization');
+      if (!auth) {
+        return new Response(JSON.stringify({
+          error: 'Unauthorized'
+        }), {
+          status: 401,
+          headers: {
+            'Content-Type': 'application/json',
+            'WWW-Authenticate': `Basic realm="${realm}"`
+          }
+        });
+      }
+      return null;
+    }
+  };
+}

package/dist/middleware/shared/cors.js

@@ -0,0 +1,28 @@
+export function cors(options = {}) {
+  const origin = options.origin || '*';
+  const allowMethods = options.methods || 'GET, POST, PUT, DELETE, OPTIONS';
+  const allowHeaders = options.headers || 'Content-Type, Authorization';
+  return {
+    preprocess(request) {
+      if (request.method === 'OPTIONS') {
+        const headers = new Headers();
+        headers.set('Access-Control-Allow-Origin', origin);
+        headers.set('Access-Control-Allow-Methods', allowMethods);
+        headers.set('Access-Control-Allow-Headers', allowHeaders);
+        return new Response(null, {
+          status: 204,
+          headers
+        });
+      }
+      return null;
+    },
+    postprocess(response) {
+      const headers = new Headers(response.headers);
+      headers.set('Access-Control-Allow-Origin', origin);
+      return new Response(response.body, {
+        ...response,
+        headers
+      });
+    }
+  };
+}

package/dist/middleware/shared/index.js

@@ -0,0 +1,3 @@
+export { cors } from './cors.js';
+export { logging } from './logging.js';
+export { basicAuth } from './basicAuth.js';

package/dist/middleware/shared/logging.js

@@ -0,0 +1,14 @@
+export function logging(options = {}) {
+  const level = options.level || 'info';
+  return {
+    preprocess(request) {
+      try {
+        const path = new URL(request.url).pathname;
+        console.log(`[${new Date().toISOString()}] ${level.toUpperCase()} ${request.method} ${path}`);
+      } catch (e) {
+        // Best-effort logging - do not throw
+      }
+      return null;
+    }
+  };
+}

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 {