@tamyla/clodo-framework 4.3.3 → 4.3.4

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [4.3.4](https://github.com/tamylaa/clodo-framework/compare/v4.3.3...v4.3.4) (2026-02-04)
+
+
+### Bug Fixes
+
+* include middleware migration doc in packaged artifact ([a6e7c9e](https://github.com/tamylaa/clodo-framework/commit/a6e7c9e8d57f0bf3c11516e418ebe71a8b4e3c0e))
+* trigger semantic-release for test fixes ([04f6f90](https://github.com/tamylaa/clodo-framework/commit/04f6f90fede7fab4ca1060fc6f490d1848a2ad55))
+
 ## [4.3.3](https://github.com/tamylaa/clodo-framework/compare/v4.3.2...v4.3.3) (2026-02-02)
 
 

package/README.md

@@ -11,9 +11,44 @@ A comprehensive framework for building enterprise-grade software architecture on
 
 > **✅ VALIDATED PROMISE**: Through comprehensive testing and validation, the Clodo Framework has been proven to deliver on its core promise of automated Cloudflare service creation. See [Framework Evolution Narrative](docs/FRAMEWORK_EVOLUTION_NARRATIVE.md) for the complete development story.
 
-## Philosophy
-
-Just like Clodo bricks snap together to build anything you can imagine, this framework provides the base components that your services snap into. Focus on your business logic while the framework handles the infrastructure, configuration, and deployment patterns.
+## 📚 Documentation
+
+### 🚀 **Quick Start** (5 minutes)
+- **[Developer Quick Start](docs/00_START_HERE.md)** - Get running immediately
+- **[Simple API Guide](docs/SIMPLE_API_GUIDE.md)** - Quick examples and usage
+
+### 🔧 **API Reference**
+- **[Programmatic API](docs/api/PROGRAMMATIC_API.md)** - Complete programmatic usage
+- **[Parameter Reference](docs/api/parameter_reference.md)** - All parameters and validation
+- **[Error Reference](docs/errors.md)** - Error codes and troubleshooting
+
+### 📖 **Guides & Migration**
+- **[Getting Started](docs/HOWTO_CONSUME_CLODO_FRAMEWORK.md)** - Step-by-step tutorial
+- **[Migration Guide](docs/MIGRATION.md)** - CLI to programmatic APIs
+- **[Framework Overview](docs/overview.md)** - Philosophy and concepts
+
+### 🏗️ **Architecture & Security**
+- **[Security](docs/SECURITY.md)** - Security considerations
+- **[Framework Evolution](docs/FRAMEWORK_EVOLUTION_NARRATIVE.md)** - Development history
+
+### 📁 **Documentation Structure**
+```
+├── docs/                    # 📖 Public documentation (npm package)
+│   ├── 00_START_HERE.md    # 🚀 Quick start guide
+│   ├── README.md           # 📚 Documentation index
+│   ├── overview.md         # 🏛️ Framework philosophy
+│   ├── api/                # 🔧 API documentation
+│   ├── integration/        # 🔗 Integration guides
+│   └── architecture/       # 🏗️ Technical architecture
+└── i-docs/                 # 🔒 Internal documentation (private)
+    ├── commercialization/  # 💼 Business strategy
+    ├── roadmap/           # 🗺️ Development planning
+    └── analysis/          # 📊 Technical analysis
+```
+
+### 🏷️ **Document Types**
+- **📖 Public** (`docs/`) - Developer usage, API reference, examples
+- **🔒 Internal** (`i-docs/`) - Business strategy, implementation details, planning
 
 ## 🎯 Key Achievements
 

package/dist/api/frameworkCapabilities.js

@@ -0,0 +1,44 @@
+/**
+ * Framework Capabilities API
+ * Provides programmatic access to framework capabilities and supported features
+ */
+
+import { FrameworkInfo } from '../version/FrameworkInfo.js';
+import { getConfig } from '../config/service-schema-config.js';
+
+/**
+ * Framework Capabilities Interface
+ * @typedef {Object} FrameworkCapabilities
+ * @property {string} version - Current framework version
+ * @property {boolean} supportsProgrammaticCreation - Whether programmatic service creation is supported
+ * @property {string[]} supportedServiceTypes - Array of supported service types
+ * @property {string[]} supportedFeatures - Array of supported features
+ * @property {boolean} hasParameterDiscovery - Whether parameter discovery API is available
+ * @property {boolean} hasUnifiedValidation - Whether unified payload validation is available
+ * @property {boolean} supportsPassthrough - Whether clodo passthrough data is supported
+ */
+
+/**
+ * Get framework capabilities
+ * @returns {FrameworkCapabilities} Framework capabilities object
+ */
+export function getFrameworkCapabilities() {
+  const config = getConfig();
+  return {
+    version: FrameworkInfo.getVersion(),
+    supportsProgrammaticCreation: true,
+    supportedServiceTypes: [...config.serviceTypes],
+    supportedFeatures: [...config.features],
+    hasParameterDiscovery: true,
+    hasUnifiedValidation: true,
+    supportsPassthrough: true
+  };
+}
+
+/**
+ * Get framework version
+ * @returns {string} Framework version string
+ */
+export function getFrameworkVersion() {
+  return FrameworkInfo.getVersion();
+}

package/dist/api/index.js

@@ -0,0 +1,7 @@
+/**
+ * Clodo Framework - API Module
+ * Framework capabilities and introspection APIs
+ */
+
+export { getFrameworkCapabilities, getFrameworkVersion } from './frameworkCapabilities.js';
+export { checkApplicationCompatibility, getSupportedApplicationVersions } from './versionCompatibility.js';

package/dist/api/versionCompatibility.js

@@ -0,0 +1,78 @@
+/**
+ * Version Compatibility API
+ * Provides version checking and compatibility validation for programmatic integration
+ */
+
+import { FrameworkInfo } from '../version/FrameworkInfo.js';
+
+/**
+ * Compatibility Result Interface
+ * @typedef {Object} CompatibilityResult
+ * @property {boolean} compatible - Whether the application version is compatible
+ * @property {string} frameworkVersion - Current framework version
+ * @property {string} [minimumApplicationVersion] - Minimum required application version
+ * @property {string[]} [breakingChanges] - List of breaking changes if incompatible
+ * @property {string[]} [recommendations] - Recommended actions or updates
+ */
+
+/**
+ * Check application compatibility with current framework version
+ * @param {string} applicationVersion - Version of the consuming application
+ * @returns {CompatibilityResult} Compatibility assessment
+ */
+export function checkApplicationCompatibility(applicationVersion) {
+  const frameworkVersion = FrameworkInfo.getVersion();
+  const result = {
+    compatible: true,
+    frameworkVersion,
+    minimumApplicationVersion: '0.1.0',
+    breakingChanges: [],
+    recommendations: []
+  };
+
+  // Parse versions for comparison
+  const parseVersion = v => v.split('.').map(n => parseInt(n, 10));
+  const [appMajor, appMinor, appPatch] = parseVersion(applicationVersion);
+  const [fwMajor, fwMinor, fwPatch] = parseVersion(frameworkVersion);
+
+  // Version compatibility logic
+  if (appMajor < 0 || appMajor === 0 && appMinor < 1) {
+    result.compatible = false;
+    result.breakingChanges.push('Application version must be 0.1.0 or higher for programmatic API support');
+  }
+
+  // Framework version specific checks
+  if (fwMajor >= 5) {
+    if (appMajor < 1) {
+      result.recommendations.push('Consider upgrading to application version 1.x for full feature support with framework 5.x');
+    }
+  }
+
+  // Known compatibility issues
+  const knownIncompatibilities = {
+    '0.0.1': ['Programmatic API not supported'],
+    '0.0.2': ['Limited parameter validation'],
+    '0.0.3': ['Missing error handling for passthrough data']
+  };
+  if (knownIncompatibilities[applicationVersion]) {
+    result.compatible = false;
+    result.breakingChanges.push(...knownIncompatibilities[applicationVersion]);
+  }
+  return result;
+}
+
+/**
+ * Get supported application versions
+ * @returns {string[]} Array of supported application version strings
+ */
+export function getSupportedApplicationVersions() {
+  return ['0.1.0', '0.2.0', '0.3.0', '1.0.0', '1.1.0'];
+}
+
+/**
+ * Get framework version (convenience function)
+ * @returns {string} Framework version string
+ */
+export function getFrameworkVersion() {
+  return FrameworkInfo.getVersion();
+}

package/dist/errors/index.js

@@ -0,0 +1,5 @@
+/**
+ * Error classes and utilities
+ */
+
+export * from './integrationErrors.js';

package/dist/errors/integrationErrors.js

@@ -0,0 +1,70 @@
+/**
+ * Integration-specific Error Classes
+ * Provides structured error handling for programmatic API integration
+ */
+
+/**
+ * Base class for integration-related errors
+ */
+export class IntegrationError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {string} code - Error code for programmatic handling
+   * @param {Object} details - Additional error details
+   */
+  constructor(message, code, details = {}) {
+    super(message);
+    this.name = 'IntegrationError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+/**
+ * Error thrown when service payload validation fails
+ */
+export class PayloadValidationError extends IntegrationError {
+  /**
+   * @param {Object} validationResult - Result from validateServicePayload
+   */
+  constructor(validationResult) {
+    super(`Service payload validation failed: ${validationResult.errors.length} errors`, 'PAYLOAD_VALIDATION_FAILED', {
+      validationResult
+    });
+    this.name = 'PayloadValidationError';
+  }
+}
+
+/**
+ * Error thrown when a parameter is not supported in the current framework version
+ */
+export class ParameterNotSupportedError extends IntegrationError {
+  /**
+   * @param {string} parameterName - Name of the unsupported parameter
+   * @param {string} frameworkVersion - Current framework version
+   */
+  constructor(parameterName, frameworkVersion) {
+    super(`Parameter '${parameterName}' not supported in framework version ${frameworkVersion}`, 'PARAMETER_NOT_SUPPORTED', {
+      parameterName,
+      frameworkVersion
+    });
+    this.name = 'ParameterNotSupportedError';
+  }
+}
+
+/**
+ * Error thrown when application version is incompatible with framework version
+ */
+export class VersionCompatibilityError extends IntegrationError {
+  /**
+   * @param {string} applicationVersion - Application version
+   * @param {string} frameworkVersion - Framework version
+   */
+  constructor(applicationVersion, frameworkVersion) {
+    super(`Application version ${applicationVersion} not compatible with framework version ${frameworkVersion}`, 'VERSION_INCOMPATIBILITY', {
+      applicationVersion,
+      frameworkVersion
+    });
+    this.name = 'VersionCompatibilityError';
+  }
+}

package/dist/index.js

@@ -40,6 +40,15 @@ export { ServiceCreator } from './service-management/ServiceCreator.js';
 export { ServiceOrchestrator } from './service-management/ServiceOrchestrator.js';
 export { InputCollector } from './service-management/InputCollector.js';
 
+// Programmatic APIs
+export { createServiceProgrammatic } from './programmatic/createService.js';
+export { deployServiceProgrammatic } from './programmatic/deployService.js';
+export { validateServiceProgrammatic } from './programmatic/validateService.js';
+export { getFrameworkCapabilities, getFrameworkVersion } from './api/frameworkCapabilities.js';
+export { getAcceptedParameters, validateServicePayload } from './validation/payloadValidation.js';
+export { IntegrationError, PayloadValidationError, ParameterNotSupportedError, VersionCompatibilityError } from './errors/integrationErrors.js';
+export { MockServiceOrchestrator, createMockFramework } from './testing/mockFramework.js';
+
 // CLI utilities (for framework CLI commands)
 export { StandardOptions } from './lib/shared/utils/cli-options.js';
 export { ConfigLoader } from './lib/shared/utils/config-loader.js';

package/dist/programmatic/deployService.js

@@ -0,0 +1,5 @@
+import { MultiDomainOrchestrator } from '../orchestration/multi-domain-orchestrator.js';
+export async function deployServiceProgrammatic(options = {}) {
+  return await MultiDomainOrchestrator.deploy(options);
+}
+export const deployService = deployServiceProgrammatic; // Backwards-compatible alias

package/dist/programmatic/index.js

@@ -0,0 +1,8 @@
+/**
+ * Clodo Framework - Programmatic APIs
+ * Programmatic service creation and management
+ */
+
+export { createServiceProgrammatic } from './createService.js';
+export { deployServiceProgrammatic } from './deployService.js';
+export { validateServiceProgrammatic } from './validateService.js';

package/dist/programmatic/validateService.js

@@ -0,0 +1,5 @@
+import { ServiceOrchestrator } from '../service-management/ServiceOrchestrator.js';
+export async function validateServiceProgrammatic(servicePath = '.', options = {}) {
+  return await ServiceOrchestrator.validate(servicePath, options);
+}
+export const validateService = validateServiceProgrammatic; // Backwards-compatible alias

package/dist/testing/index.js

@@ -0,0 +1,6 @@
+/**
+ * Clodo Framework - Testing Utilities
+ * Mock frameworks and testing helpers for programmatic APIs
+ */
+
+export { MockServiceOrchestrator, createMockFramework } from './mockFramework.js';

package/dist/testing/mockFramework.js

@@ -0,0 +1,236 @@
+/**
+ * Mock Framework for Integration Testing
+ * Provides mock implementations for testing programmatic API consumers
+ */
+
+import { getConfig } from '../config/service-schema-config.js';
+import { validateServicePayload } from '../validation/payloadValidation.js';
+
+/**
+ * Mock Service Orchestrator for testing
+ * Provides predictable behavior without file system operations
+ */
+export class MockServiceOrchestrator {
+  constructor() {
+    this.createdServices = [];
+    this.reset();
+  }
+
+  /**
+   * Mock service creation - validates payload and stores for testing
+   * @param {Object} payload - Service payload to create
+   * @param {Object} options - Creation options
+   * @returns {Promise<Object>} Creation result
+   */
+  async createService(payload, options = {}) {
+    // Validate payload using real validation logic
+    const validation = validateServicePayload(payload);
+    if (!validation.valid) {
+      return {
+        success: false,
+        errors: validation.errors.map(e => e.message),
+        warnings: validation.warnings.map(w => w.message)
+      };
+    }
+
+    // Store for testing purposes
+    const serviceId = `mock-${payload.serviceName}-${Date.now()}`;
+    const servicePath = `/mock/path/${payload.serviceName}`;
+    const serviceRecord = {
+      ...payload,
+      serviceId,
+      servicePath,
+      createdAt: new Date().toISOString(),
+      options
+    };
+    this.createdServices.push(serviceRecord);
+    return {
+      success: true,
+      serviceId,
+      servicePath,
+      warnings: validation.warnings.map(w => w.message)
+    };
+  }
+
+  /**
+   * Get all services created during testing
+   * @returns {Array} Array of created service records
+   */
+  getCreatedServices() {
+    return [...this.createdServices];
+  }
+
+  /**
+   * Find a service by name
+   * @param {string} serviceName - Name of the service to find
+   * @returns {Object|null} Service record or null if not found
+   */
+  findService(serviceName) {
+    return this.createdServices.find(s => s.serviceName === serviceName) || null;
+  }
+
+  /**
+   * Reset the mock state
+   */
+  reset() {
+    this.createdServices = [];
+  }
+
+  /**
+   * Get creation statistics
+   * @returns {Object} Statistics about mock operations
+   */
+  getStats() {
+    return {
+      totalCreated: this.createdServices.length,
+      serviceTypes: [...new Set(this.createdServices.map(s => s.serviceType))],
+      features: [...new Set(this.createdServices.flatMap(s => s.features || []))]
+    };
+  }
+}
+
+/**
+ * Create a complete mock framework for testing
+ * @returns {Object} Mock framework with all necessary APIs
+ */
+export function createMockFramework() {
+  const mockOrchestrator = new MockServiceOrchestrator();
+  return {
+    // Mock ServiceOrchestrator
+    ServiceOrchestrator: MockServiceOrchestrator,
+    // Mock programmatic creation function
+    createService: (payload, options) => mockOrchestrator.createService(payload, options),
+    // Mock parameter discovery (returns real parameter definitions)
+    getAcceptedParameters: () => {
+      const config = getConfig();
+      return {
+        serviceName: {
+          name: 'serviceName',
+          type: 'string',
+          required: true,
+          description: 'Unique identifier for the service',
+          validationRules: [{
+            rule: 'pattern',
+            value: '^[a-z0-9-]+$',
+            message: 'Lowercase letters, numbers and hyphens only'
+          }, {
+            rule: 'minLength',
+            value: 3,
+            message: 'At least 3 characters'
+          }, {
+            rule: 'maxLength',
+            value: 50,
+            message: 'At most 50 characters'
+          }]
+        },
+        serviceType: {
+          name: 'serviceType',
+          type: 'string',
+          required: true,
+          description: 'Type of service to create',
+          enum: config.serviceTypes
+        },
+        domain: {
+          name: 'domain',
+          type: 'string',
+          required: true,
+          description: 'Domain for the service',
+          validationRules: [{
+            rule: 'pattern',
+            value: '^([a-z0-9]+(-[a-z0-9]+)*\\.)+[a-z]{2,}$',
+            message: 'Must be a valid domain'
+          }]
+        },
+        features: {
+          name: 'features',
+          type: 'array',
+          required: false,
+          description: 'Features to enable',
+          enum: config.features
+        },
+        clodo: {
+          name: 'clodo',
+          type: 'object',
+          required: false,
+          description: 'Passthrough data for clodo-application specific configuration'
+        }
+      };
+    },
+    // Mock framework capabilities
+    getFrameworkCapabilities: () => {
+      const config = getConfig();
+      return {
+        version: '4.3.2-mock',
+        supportsProgrammaticCreation: true,
+        supportedServiceTypes: [...config.serviceTypes],
+        supportedFeatures: [...config.features],
+        hasParameterDiscovery: true,
+        hasUnifiedValidation: true,
+        supportsPassthrough: true
+      };
+    },
+    // Mock framework version
+    getFrameworkVersion: () => '4.3.2-mock',
+    // Access to the underlying mock orchestrator for advanced testing
+    _mockOrchestrator: mockOrchestrator
+  };
+}
+
+/**
+ * Helper function to create a mock service payload for testing
+ * @param {Object} overrides - Properties to override in the default payload
+ * @returns {Object} Complete service payload
+ */
+export function createMockServicePayload(overrides = {}) {
+  return {
+    serviceName: 'test-service',
+    serviceType: 'api-service',
+    domain: 'test.example.com',
+    description: 'Test service description',
+    features: ['d1', 'metrics'],
+    ...overrides
+  };
+}
+
+/**
+ * Helper function to assert service creation results
+ * @param {Object} result - Result from createService
+ * @param {Object} expected - Expected properties
+ */
+export function assertServiceCreationResult(result, expected = {}) {
+  const defaults = {
+    success: true,
+    hasServiceId: true,
+    hasServicePath: true,
+    errorCount: 0,
+    warningCount: 0
+  };
+  const checks = {
+    ...defaults,
+    ...expected
+  };
+  if (checks.success) {
+    expect(result.success).toBe(true);
+    if (checks.hasServiceId) {
+      expect(result.serviceId).toBeDefined();
+      expect(typeof result.serviceId).toBe('string');
+    }
+    if (checks.hasServicePath) {
+      expect(result.servicePath).toBeDefined();
+      expect(typeof result.servicePath).toBe('string');
+    }
+  } else {
+    expect(result.success).toBe(false);
+  }
+  if (checks.errorCount > 0) {
+    expect(result.errors).toBeDefined();
+    expect(Array.isArray(result.errors)).toBe(true);
+    expect(result.errors).toHaveLength(checks.errorCount);
+  }
+  if (checks.warningCount >= 0) {
+    if (result.warnings) {
+      expect(Array.isArray(result.warnings)).toBe(true);
+      expect(result.warnings).toHaveLength(checks.warningCount);
+    }
+  }
+}

package/dist/validation/index.js

@@ -0,0 +1,6 @@
+/**
+ * Clodo Framework - Validation Module
+ * Payload validation and parameter discovery
+ */
+
+export { validateServicePayload, getAcceptedParameters, getParameterDefinitions } from './payloadValidation.js';

package/dist/validation/payloadValidation.js

@@ -20,7 +20,7 @@ export const ServicePayloadSchema = z.object({
   bindings: z.array(z.string()).optional(),
   resources: z.record(z.any()).optional(),
   specs: z.record(z.any()).optional(),
-  clodo: z.record(z.any()).optional()
+  clodo: z.any().optional()
 });
 export function validateServicePayload(payload) {
   const result = {
@@ -59,11 +59,19 @@ export function validateServicePayload(payload) {
     // Handle Zod-like errors with an errors array
     if (err && err.errors && Array.isArray(err.errors)) {
       for (const e of err.errors) {
-        result.errors.push({
-          field: (e.path || []).join('.'),
-          code: 'SCHEMA_VALIDATION',
-          message: e.message
-        });
+        if (e && typeof e === 'object') {
+          result.errors.push({
+            field: (e.path || []).join('.'),
+            code: 'SCHEMA_VALIDATION',
+            message: e.message
+          });
+        } else {
+          result.errors.push({
+            field: 'unknown',
+            code: 'SCHEMA_VALIDATION',
+            message: `Unknown validation error: ${JSON.stringify(e)}`
+          });
+        }
       }
     }
     // Some environments stringify Zod errors into err.message (JSON array) - try to parse
@@ -142,12 +150,42 @@ export function getParameterDefinitions() {
         message: 'Must be a valid domain'
       }]
     },
+    description: {
+      name: 'description',
+      type: 'string',
+      required: false,
+      description: 'Optional description of the service'
+    },
+    template: {
+      name: 'template',
+      type: 'string',
+      required: false,
+      description: 'Template to use for service creation'
+    },
     features: {
       name: 'features',
       type: 'array',
       required: false,
       description: 'Features to enable',
-      enum: VALID_FEATURES
+      enum: VALID_FEATURES()
+    },
+    bindings: {
+      name: 'bindings',
+      type: 'array',
+      required: false,
+      description: 'Service bindings configuration'
+    },
+    resources: {
+      name: 'resources',
+      type: 'object',
+      required: false,
+      description: 'Resource specifications'
+    },
+    specs: {
+      name: 'specs',
+      type: 'object',
+      required: false,
+      description: 'Additional specifications'
     },
     clodo: {
       name: 'clodo',
@@ -156,4 +194,7 @@ export function getParameterDefinitions() {
       description: 'Passthrough data for clodo-application specific configuration'
     }
   };
-}
+}
+
+// Alias for backward compatibility and API consistency
+export const getAcceptedParameters = getParameterDefinitions;