@tamyla/clodo-framework 4.4.0 → 4.5.0

package/dist/utilities/index.js

@@ -62,4 +62,137 @@ export { ServiceBindingClient, RPCClient, ServiceRouter } from './bindings/index
 // ============================================================
 
 // Analytics Engine
-export { AnalyticsWriter, EventTracker, MetricsCollector } from './analytics/index.js';
+export { AnalyticsWriter, EventTracker, MetricsCollector } from './analytics/index.js';
+
+// ============================================================
+// STANDALONE UTILITY FUNCTIONS
+// ============================================================
+
+// AI Utilities
+/**
+ * Run an AI model directly
+ * @param {Object} aiBinding - AI binding from env
+ * @param {string} model - Model name
+ * @param {Object} inputs - Model inputs
+ * @returns {Promise<Object>} Model response
+ */
+export async function runAIModel(aiBinding, model, inputs) {
+  const {
+    AIClient
+  } = await import('./ai/index.js');
+  const ai = new AIClient(aiBinding);
+  return ai.run(model, inputs);
+}
+
+/**
+ * Stream AI response
+ * @param {Object} aiBinding - AI binding from env
+ * @param {string} model - Model name
+ * @param {Object} inputs - Model inputs
+ * @returns {Promise<Response>} Streaming response
+ */
+export async function streamAIResponse(aiBinding, model, inputs) {
+  const {
+    AIClient,
+    streamResponse
+  } = await import('./ai/index.js');
+  const ai = new AIClient(aiBinding);
+  const stream = await ai.run(model, {
+    ...inputs,
+    stream: true
+  });
+  return streamResponse(stream);
+}
+
+/**
+ * Format AI prompt with context
+ * @param {string} prompt - Base prompt
+ * @param {Object} context - Context data
+ * @returns {string} Formatted prompt
+ */
+export function formatAIPrompt(prompt, context = {}) {
+  let formatted = prompt;
+
+  // Replace placeholders like {{key}} with context values
+  for (const [key, value] of Object.entries(context)) {
+    const placeholder = new RegExp(`{{${key}}}`, 'g');
+    formatted = formatted.replace(placeholder, String(value));
+  }
+  return formatted;
+}
+
+// Vectorize Utilities
+/**
+ * Query vectors from Vectorize index
+ * @param {Object} vectorizeBinding - Vectorize binding from env
+ * @param {number[]} vector - Query vector
+ * @param {Object} options - Query options
+ * @returns {Promise<Object>} Query results
+ */
+export async function queryVectors(vectorizeBinding, vector, options = {}) {
+  const {
+    VectorStore
+  } = await import('./vectorize/index.js');
+  const store = new VectorStore(vectorizeBinding);
+  return store.query(vector, options);
+}
+
+/**
+ * Upsert vectors to Vectorize index
+ * @param {Object} vectorizeBinding - Vectorize binding from env
+ * @param {Array} vectors - Vectors to upsert
+ * @returns {Promise<Object>} Upsert results
+ */
+export async function upsertVectors(vectorizeBinding, vectors) {
+  const {
+    VectorStore
+  } = await import('./vectorize/index.js');
+  const store = new VectorStore(vectorizeBinding);
+  return store.upsert(vectors);
+}
+
+// KV Utilities
+/**
+ * Get value from KV storage
+ * @param {Object} kvBinding - KV binding from env
+ * @param {string} key - Key to retrieve
+ * @param {Object} options - Get options
+ * @returns {Promise<*>} Retrieved value
+ */
+export async function getKV(kvBinding, key, options = {}) {
+  const {
+    KVStorage
+  } = await import('./kv/index.js');
+  const kv = new KVStorage(kvBinding);
+  return kv.get(key, options);
+}
+
+/**
+ * Put value in KV storage
+ * @param {Object} kvBinding - KV binding from env
+ * @param {string} key - Key to set
+ * @param {*} value - Value to store
+ * @param {Object} options - Put options
+ * @returns {Promise<void>}
+ */
+export async function putKV(kvBinding, key, value, options = {}) {
+  const {
+    KVStorage
+  } = await import('./kv/index.js');
+  const kv = new KVStorage(kvBinding);
+  return kv.set(key, value, options);
+}
+
+/**
+ * List keys from KV storage
+ * @param {Object} kvBinding - KV binding from env
+ * @param {Object} options - List options
+ * @returns {Promise<Object>} List results
+ */
+export async function listKV(kvBinding, options = {}) {
+  const {
+    KVStorage
+  } = await import('./kv/index.js');
+  const kv = new KVStorage(kvBinding);
+  return kv.list(options);
+}

package/dist/utils/config/environment-var-normalizer.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+
+/**
+ * Environment Variable Normalizer
+ * Standardizes service environment variable configuration across multiple formats
+ * 
+ * Supports three legacy formats for backward compatibility:
+ * 1. Flat structure (recommended):
+ *    service.vars = { API_KEY: "value" }
+ * 
+ * 2. Nested structure (deprecated):
+ *    service.environment = { vars: { API_KEY: "value" }, secrets: [...] }
+ * 
+ * 3. Per-environment overrides (deprecated):
+ *    service.env = { production: { vars: { ... } }, staging: { vars: { ... } } }
+ * 
+ * @module EnvironmentVarNormalizer
+ */
+
+/**
+ * EnvironmentVarNormalizer
+ * Handles conversion and validation of service environment variable formats
+ */
+export class EnvironmentVarNormalizer {
+  /**
+   * Normalize service configuration to standard flat structure
+   * Accepts all 3 formats and converts to unified output
+   * 
+   * @param {Object} service - Service configuration object
+   * @param {Object} options - Normalization options
+   * @param {boolean} options.warnOnDeprecated - Log deprecation warnings (default: true)
+   * @param {boolean} options.throwOnConflict - Throw error if conflicting formats found (default: false)
+   * @returns {Object} Normalized service config with flat vars and secrets
+   */
+  static normalize(service, options = {}) {
+    const {
+      warnOnDeprecated = true,
+      throwOnConflict = false
+    } = options;
+    const result = {
+      ...service,
+      vars: {},
+      secrets: [],
+      _normalizationInfo: {
+        formatDetected: null,
+        deprecatedFormatsFound: [],
+        warnings: []
+      }
+    };
+
+    // Check which formats are present
+    const hasFlat = 'vars' in service;
+    const hasNested = 'environment' in service && service.environment?.vars;
+    const hasPerEnv = 'env' in service && this.hasPerEnvironmentVars(service.env);
+
+    // Track what we found
+    const formatsFound = [];
+    if (hasFlat) formatsFound.push('flat');
+    if (hasNested) formatsFound.push('nested');
+    if (hasPerEnv) formatsFound.push('per-environment');
+
+    // Handle conflicts
+    if (formatsFound.length > 1) {
+      const warning = `Service '${service.name}' uses multiple var formats: [${formatsFound.join(', ')}]. Using flat format as primary.`;
+      result._normalizationInfo.warnings.push(warning);
+      if (warnOnDeprecated) {
+        console.warn(`⚠️  ${warning}`);
+      }
+      if (throwOnConflict) {
+        throw new Error(`Configuration conflict: Service '${service.name}' has conflicting var formats. ` + `Please use only the flat format: service.vars = {...}`);
+      }
+    }
+
+    // Extract flat format (primary)
+    if (hasFlat && service.vars && typeof service.vars === 'object') {
+      result.vars = {
+        ...service.vars
+      };
+      result._normalizationInfo.formatDetected = 'flat';
+    }
+
+    // Extract flat secrets
+    if (Array.isArray(service.secrets)) {
+      result.secrets = [...service.secrets];
+    }
+
+    // Extract nested format (deprecated)
+    if (hasNested) {
+      result._normalizationInfo.deprecatedFormatsFound.push('nested');
+      if (warnOnDeprecated) {
+        console.warn(`⚠️  DEPRECATION: Service '${service.name}' uses nested format (service.environment.vars). ` + `This will be removed in v5.0.0. Use flat format instead: service.vars = {...}`);
+      }
+      const nestedVars = service.environment.vars || {};
+      Object.assign(result.vars, nestedVars);
+
+      // Extract secrets from nested format (only if not already set from flat)
+      if (Array.isArray(service.environment.secrets) && result.secrets.length === 0) {
+        result.secrets = [...service.environment.secrets];
+      }
+      if (!result._normalizationInfo.formatDetected) {
+        result._normalizationInfo.formatDetected = 'nested';
+      }
+    }
+
+    // Extract per-environment format (deprecated)
+    if (hasPerEnv) {
+      result._normalizationInfo.deprecatedFormatsFound.push('per-environment');
+      if (warnOnDeprecated) {
+        console.warn(`⚠️  DEPRECATION: Service '${service.name}' uses per-environment format (service.env.{environment}.vars). ` + `This will be removed in v5.0.0. Use flat format instead: service.vars = {...} ` + `(Clodo will handle environment-specific overrides internally)`);
+      }
+
+      // Merge all environment vars
+      for (const [envName, envConfig] of Object.entries(service.env)) {
+        if (envConfig?.vars && typeof envConfig.vars === 'object') {
+          Object.assign(result.vars, envConfig.vars);
+        }
+      }
+      if (!result._normalizationInfo.formatDetected) {
+        result._normalizationInfo.formatDetected = 'per-environment';
+      }
+    }
+
+    // Remove deprecated properties from result
+    if (hasNested) {
+      delete result.environment;
+    }
+    if (hasPerEnv) {
+      // Don't delete env - it might have other valid properties like name
+      // Just remove the vars from each environment config
+      if (result.env && typeof result.env === 'object') {
+        for (const envConfig of Object.values(result.env)) {
+          if (envConfig?.vars) {
+            delete envConfig.vars;
+          }
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Check if env object contains per-environment var configs
+   * @private
+   */
+  static hasPerEnvironmentVars(env) {
+    if (!env || typeof env !== 'object') return false;
+    for (const envConfig of Object.values(env)) {
+      if (envConfig?.vars && typeof envConfig.vars === 'object') {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Get deprecation timeline for the current version
+   * @param {string} currentVersion - Current framework version (e.g., "4.4.1")
+   * @returns {Object} Deprecation timeline with dates and versions
+   */
+  static getDeprecationTimeline(currentVersion = '4.4.1') {
+    return {
+      current: {
+        version: currentVersion,
+        status: 'DEPRECATED (but supported)',
+        message: 'Nested and per-environment formats are still supported but generate warnings'
+      },
+      v4_5_0: {
+        version: '4.5.0',
+        eta: 'Q2 2026 (May 2026)',
+        status: 'WARNINGS REQUIRED',
+        message: 'All uses of deprecated formats must emit console warnings during deployment'
+      },
+      v5_0_0: {
+        version: '5.0.0',
+        eta: 'Q3 2026 (July 2026)',
+        status: 'REMOVAL',
+        message: 'Nested and per-environment formats will no longer be supported. Only flat format accepted.'
+      }
+    };
+  }
+
+  /**
+   * Validate that vars follow naming conventions
+   * @param {Object} vars - Variables object
+   * @returns {Object} Validation result with issues array
+   */
+  static validateNamingConventions(vars) {
+    const issues = [];
+    if (!vars || typeof vars !== 'object') {
+      return {
+        valid: true,
+        issues
+      };
+    }
+    for (const [key, value] of Object.entries(vars)) {
+      // Check for hyphens first
+      if (key.includes('-')) {
+        issues.push({
+          key,
+          issue: 'Hyphens not allowed in variable names',
+          message: `Variable name '${key}' contains hyphens. Use underscores instead: ${key.replace(/-/g, '_')}`,
+          severity: 'error'
+        });
+        continue; // Skip other checks for this key
+      }
+
+      // Check for dots
+      if (key.includes('.')) {
+        issues.push({
+          key,
+          issue: 'Dots not allowed in variable names',
+          message: `Variable name '${key}' contains dots. Use underscores instead: ${key.replace(/\./g, '_')}`,
+          severity: 'error'
+        });
+        continue; // Skip other checks for this key
+      }
+
+      // Check for valid identifier format
+      if (!/^[A-Z_][A-Z0-9_]*$/.test(key)) {
+        issues.push({
+          key,
+          issue: 'Invalid variable name format',
+          message: `Variable name '${key}' doesn't follow SCREAMING_SNAKE_CASE convention. ` + `Use uppercase letters, numbers, and underscores only (must start with letter or underscore).`,
+          severity: 'warning'
+        });
+      }
+    }
+    return {
+      valid: issues.filter(i => i.severity === 'error').length === 0,
+      issues
+    };
+  }
+}

package/dist/validation/environmentGuard.js

@@ -0,0 +1,172 @@
+/**
+ * Environment Guard — Validates Cloudflare Worker env bindings at startup
+ * 
+ * Catches missing bindings early with descriptive errors instead of
+ * failing deep in handler logic with cryptic "Cannot read property of undefined".
+ * 
+ * @example
+ * import { createEnvironmentGuard } from '@tamyla/clodo-framework';
+ * 
+ * const guard = createEnvironmentGuard({
+ *   required: ['KV_DATA', 'AI', 'SECRET_KEY'],
+ *   optional: ['DEBUG', 'ANTHROPIC_API_KEY'],
+ *   validate: {
+ *     SECRET_KEY: (v) => typeof v === 'string' && v.length >= 32
+ *   }
+ * });
+ * 
+ * // In your Worker fetch handler:
+ * export default {
+ *   async fetch(request, env, ctx) {
+ *     guard.check(env); // throws if bindings are missing
+ *     // ... handle request
+ *   }
+ * };
+ * 
+ * @module @tamyla/clodo-framework/validation/environmentGuard
+ */
+
+/**
+ * @typedef {Object} EnvironmentGuardConfig
+ * @property {string[]} required - Binding names that MUST be present
+ * @property {string[]} [optional=[]] - Binding names that MAY be present
+ * @property {Object<string, Function>} [validate={}] - Custom validators per binding
+ * @property {boolean} [throwOnMissing=true] - Throw on missing required binding (false = return report)
+ */
+
+export class EnvironmentGuard {
+  /**
+   * @param {EnvironmentGuardConfig} config
+   */
+  constructor(config = {}) {
+    this.required = config.required || [];
+    this.optional = config.optional || [];
+    this.validators = config.validate || {};
+    this.throwOnMissing = config.throwOnMissing !== false;
+    this._checked = false;
+  }
+
+  /**
+   * Validate env bindings. Call once at startup or in the fetch handler.
+   * @param {Object} env - Cloudflare Worker environment
+   * @returns {{ valid: boolean, missing: string[], invalid: string[], present: string[], warnings: string[] }}
+   * @throws {Error} If throwOnMissing is true and required bindings are missing
+   */
+  check(env) {
+    const result = {
+      valid: true,
+      missing: [],
+      invalid: [],
+      present: [],
+      warnings: []
+    };
+
+    // Check required bindings
+    for (const name of this.required) {
+      if (env[name] === undefined || env[name] === null) {
+        result.missing.push(name);
+        result.valid = false;
+      } else {
+        result.present.push(name);
+      }
+    }
+
+    // Check optional bindings (warn if missing, don't fail)
+    for (const name of this.optional) {
+      if (env[name] === undefined || env[name] === null) {
+        result.warnings.push(`Optional binding '${name}' is not configured`);
+      } else {
+        result.present.push(name);
+      }
+    }
+
+    // Run custom validators
+    for (const [name, validator] of Object.entries(this.validators)) {
+      if (env[name] !== undefined && env[name] !== null) {
+        try {
+          const isValid = validator(env[name]);
+          if (!isValid) {
+            result.invalid.push(name);
+            result.valid = false;
+          }
+        } catch (err) {
+          result.invalid.push(name);
+          result.valid = false;
+        }
+      }
+    }
+    this._checked = true;
+    if (!result.valid && this.throwOnMissing) {
+      const parts = [];
+      if (result.missing.length) {
+        parts.push(`Missing required bindings: ${result.missing.join(', ')}`);
+      }
+      if (result.invalid.length) {
+        parts.push(`Invalid bindings: ${result.invalid.join(', ')}`);
+      }
+      throw new Error(`[EnvironmentGuard] Environment validation failed.\n${parts.join('\n')}\n\n` + `Hint: Check your wrangler.toml bindings and .dev.vars for secrets.`);
+    }
+    return result;
+  }
+
+  /**
+   * Create a middleware-compatible object that validates env on each request (with caching).
+   * Can be used with router.use() or composeMiddleware().
+   * @returns {Object} Middleware object with preprocess method
+   */
+  asMiddleware() {
+    const guard = this;
+    return {
+      preprocess(request, env) {
+        if (!guard._checked) {
+          guard.check(env);
+        }
+        return null; // pass through
+      }
+    };
+  }
+
+  /**
+   * Generate a TypeScript Env interface from the configured bindings.
+   * Useful for DX — generates type definitions from guard config.
+   * @param {Object} [bindingTypes={}] - Map of binding name → TypeScript type
+   * @returns {string} TypeScript interface definition
+   */
+  generateEnvType(bindingTypes = {}) {
+    const lines = ['interface Env {'];
+
+    // Known Cloudflare binding types
+    const defaultTypes = {
+      KVNamespace: 'KVNamespace',
+      D1Database: 'D1Database',
+      R2Bucket: 'R2Bucket',
+      Ai: 'Ai',
+      VectorizeIndex: 'VectorizeIndex',
+      Queue: 'Queue',
+      DurableObjectNamespace: 'DurableObjectNamespace',
+      Fetcher: 'Fetcher',
+      AnalyticsEngineDataset: 'AnalyticsEngineDataset',
+      SendEmail: 'SendEmail',
+      Hyperdrive: 'Hyperdrive'
+    };
+    for (const name of this.required) {
+      const type = bindingTypes[name] || 'unknown';
+      lines.push(`  ${name}: ${type};`);
+    }
+    for (const name of this.optional) {
+      const type = bindingTypes[name] || 'string';
+      lines.push(`  ${name}?: ${type};`);
+    }
+    lines.push('}');
+    return lines.join('\n');
+  }
+}
+
+/**
+ * Create an environment guard — factory function
+ * @param {EnvironmentGuardConfig} config
+ * @returns {EnvironmentGuard}
+ */
+export function createEnvironmentGuard(config = {}) {
+  return new EnvironmentGuard(config);
+}