@tamyla/clodo-framework 4.0.15 → 4.1.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [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)
 
 

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/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/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
    */

package/dist/validation/payloadValidation.js

@@ -0,0 +1,159 @@
+import { z } from 'zod';
+
+// Allowed enums
+import { getConfig } from '../config/service-schema-config.js';
+export const VALID_SERVICE_TYPES = () => getConfig().serviceTypes;
+export const VALID_FEATURES = () => getConfig().features;
+
+// Zod schema with refined validations
+export const ServicePayloadSchema = z.object({
+  serviceName: z.string().min(3).max(50).regex(/^[a-z0-9-]+$/, 'serviceName must be lowercase letters, numbers and hyphens only'),
+  serviceType: z.string().refine(v => VALID_SERVICE_TYPES().includes(v), {
+    message: `Invalid serviceType. Expected one of: ${VALID_SERVICE_TYPES().join(', ')}`
+  }),
+  domain: z.string().min(3).regex(/^([a-z0-9]+(-[a-z0-9]+)*\.)+[a-z]{2,}$/, 'domain must be a valid domain name'),
+  description: z.string().optional(),
+  template: z.string().optional(),
+  features: z.array(z.string().refine(v => VALID_FEATURES().includes(v), {
+    message: `Invalid feature. Expected one of: ${VALID_FEATURES().join(', ')}`
+  })).optional(),
+  bindings: z.array(z.string()).optional(),
+  resources: z.record(z.any()).optional(),
+  specs: z.record(z.any()).optional(),
+  clodo: z.record(z.any()).optional()
+});
+export function validateServicePayload(payload) {
+  const result = {
+    valid: true,
+    errors: [],
+    warnings: []
+  };
+  try {
+    ServicePayloadSchema.parse(payload);
+
+    // Additional semantic checks
+    if (payload.features && Array.isArray(payload.features)) {
+      const duplicates = payload.features.filter((v, i, a) => a.indexOf(v) !== i);
+      if (duplicates.length) {
+        result.warnings.push({
+          field: 'features',
+          code: 'DUPLICATE_FEATURES',
+          message: `Duplicate features: ${[...new Set(duplicates)].join(', ')}`
+        });
+      }
+
+      // Check for unknown features if config changed at runtime
+      const configured = VALID_FEATURES();
+      const unknown = payload.features.filter(f => !configured.includes(f));
+      if (unknown.length) {
+        result.warnings.push({
+          field: 'features',
+          code: 'UNKNOWN_FEATURES',
+          message: `Unknown features: ${[...new Set(unknown)].join(', ')}`
+        });
+      }
+    }
+  } catch (err) {
+    result.valid = false;
+
+    // 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
+        });
+      }
+    }
+    // Some environments stringify Zod errors into err.message (JSON array) - try to parse
+    else if (typeof err?.message === 'string' && err.message.trim().startsWith('[')) {
+      try {
+        const parsed = JSON.parse(err.message);
+        if (Array.isArray(parsed)) {
+          for (const e of parsed) {
+            const field = (e.path || []).join('.');
+            const msg = e.message || JSON.stringify(e);
+            result.errors.push({
+              field,
+              code: 'SCHEMA_VALIDATION',
+              message: msg
+            });
+          }
+        } else {
+          result.errors.push({
+            code: 'UNKNOWN',
+            message: err.message
+          });
+        }
+      } catch (parseErr) {
+        result.errors.push({
+          code: 'UNKNOWN',
+          message: err.message
+        });
+      }
+    } else {
+      result.errors.push({
+        code: 'UNKNOWN',
+        message: err.message
+      });
+    }
+  }
+  return result;
+}
+
+// Parameter metadata for discovery (derived from schema)
+export function getParameterDefinitions() {
+  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: VALID_SERVICE_TYPES()
+    },
+    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: VALID_FEATURES
+    },
+    clodo: {
+      name: 'clodo',
+      type: 'object',
+      required: false,
+      description: 'Passthrough data for clodo-application specific configuration'
+    }
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tamyla/clodo-framework",
-  "version": "4.0.15",
+  "version": "4.1.0",
   "description": "Reusable framework for Clodo-style software architecture on Cloudflare Workers + D1",
   "type": "module",
   "sideEffects": [
@@ -153,7 +153,8 @@
     "commander": "^11.0.0",
     "inquirer": "^12.10.0",
     "uuid": "^13.0.0",
-    "wrangler": ">=3.0.0"
+    "wrangler": ">=3.0.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@babel/cli": "^7.23.0",

package/scripts/debug_validate_payload.mjs

@@ -0,0 +1,12 @@
+import { validateServicePayload } from '../src/validation/payloadValidation.js';
+
+const cases = [
+  { payload: { serviceName: 'Invalid Name', serviceType: 'generic', domain: 'example.com' }, name: 'invalid name' },
+  { payload: { serviceName: 'svc2', serviceType: 'unknown-type', domain: 'example.com' }, name: 'invalid type' },
+  { payload: { serviceName: 'svc3', serviceType: 'generic', domain: 'example.com', features: ['d1','nonsense'] }, name: 'invalid feature' }
+];
+
+for (const c of cases) {
+  const res = validateServicePayload(c.payload);
+  console.log('CASE:', c.name, JSON.stringify(res, null, 2));
+}