@tamyla/clodo-framework 4.4.1 → 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/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);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tamyla/clodo-framework",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "description": "Reusable framework for Clodo-style software architecture on Cloudflare Workers + D1",
   "type": "module",
   "sideEffects": [
@@ -17,6 +17,7 @@
     "./schema": "./dist/schema/SchemaManager.js",
     "./modules": "./dist/modules/ModuleManager.js",
     "./routing": "./dist/routing/EnhancedRouter.js",
+    "./routing/context": "./dist/routing/RequestContext.js",
     "./handlers": "./dist/handlers/GenericRouteHandler.js",
     "./config": "./dist/config/index.js",
     "./config/customers": "./dist/config/customers.js",
@@ -34,9 +35,11 @@
     "./programmatic": "./dist/programmatic/index.js",
     "./api": "./dist/api/index.js",
     "./validation": "./dist/validation/index.js",
+    "./validation/env": "./dist/validation/environmentGuard.js",
     "./errors": "./dist/errors/index.js",
     "./testing": "./dist/testing/index.js",
     "./middleware": "./dist/middleware/index.js",
+    "./middleware/factories": "./dist/middleware/factories.js",
     "./modules/security": "./dist/modules/security.js",
     "./utilities": "./dist/utilities/index.js",
     "./utilities/storage": "./dist/utilities/storage/r2.js",

package/scripts/repro-clodo.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * Reproduction script for Express-like router.get/router.post API
+ * 
+ * This script demonstrates both the original registerRoute() API 
+ * and the new Express-like convenience methods (router.get(), router.post(), etc.)
+ * 
+ * Run: node scripts/repro-clodo.js
+ */
+
+import { createEnhancedRouter } from '../src/routing/EnhancedRouter.js';
+
+console.log('🧪 CLODO Framework Router API Compatibility Test\n');
+console.log('=' .repeat(60));
+
+// Mock D1 Client
+const mockD1Client = {
+  prepare: () => ({ bind: () => ({}) }),
+};
+
+// Create router instance
+const router = createEnhancedRouter(mockD1Client, {
+  requireAuth: false,
+  allowPublicRead: true
+});
+
+console.log('\n📋 Router Instance Properties:');
+console.log('   Keys:', Object.keys(router).sort());
+console.log('   d1Client present:', !!router.d1Client);
+console.log('   options present:', !!router.options);
+console.log('   routes Map present:', router.routes instanceof Map);
+console.log('   genericHandlers present:', !!router.genericHandlers);
+
+console.log('\n📋 Express-like Methods Available:');
+const expressLikeMethods = ['get', 'post', 'put', 'patch', 'delete'];
+for (const method of expressLikeMethods) {
+  console.log(`   typeof router.${method}:`, typeof router[method]);
+}
+
+console.log('\n🔧 Testing Express-like API:');
+
+// Test 1: router.get()
+console.log('\n  Test 1: router.get()');
+try {
+  router.get('/api/users', (req) => new Response('GET /api/users'));
+  console.log('    ✅ router.get() registered successfully');
+  console.log('    ✓ Route key:', 'GET /api/users');
+  console.log('    ✓ Handler registered:', router.routes.has('GET /api/users'));
+} catch (e) {
+  console.log('    ❌ router.get() failed:', e.message);
+}
+
+// Test 2: router.post()
+console.log('\n  Test 2: router.post()');
+try {
+  router.post('/api/users', (req) => new Response('POST /api/users', { status: 201 }));
+  console.log('    ✅ router.post() registered successfully');
+  console.log('    ✓ Route key:', 'POST /api/users');
+  console.log('    ✓ Handler registered:', router.routes.has('POST /api/users'));
+} catch (e) {
+  console.log('    ❌ router.post() failed:', e.message);
+}
+
+// Test 3: router.get() with parameters
+console.log('\n  Test 3: router.get() with parameters');
+try {
+  router.get('/api/users/:id', (req, id) => new Response(`GET /api/users/${id}`));
+  console.log('    ✅ router.get() with parameters registered successfully');
+  console.log('    ✓ Route key:', 'GET /api/users/:id');
+  console.log('    ✓ Handler registered:', router.routes.has('GET /api/users/:id'));
+} catch (e) {
+  console.log('    ❌ router.get() with parameters failed:', e.message);
+}
+
+// Test 4: router.patch()
+console.log('\n  Test 4: router.patch()');
+try {
+  router.patch('/api/users/:id', (req, id) => new Response(`PATCH /api/users/${id}`));
+  console.log('    ✅ router.patch() registered successfully');
+  console.log('    ✓ Route key:', 'PATCH /api/users/:id');
+  console.log('    ✓ Handler registered:', router.routes.has('PATCH /api/users/:id'));
+} catch (e) {
+  console.log('    ❌ router.patch() failed:', e.message);
+}
+
+// Test 5: router.delete()
+console.log('\n  Test 5: router.delete()');
+try {
+  router.delete('/api/users/:id', (req, id) => new Response(`DELETE /api/users/${id}`));
+  console.log('    ✅ router.delete() registered successfully');
+  console.log('    ✓ Route key:', 'DELETE /api/users/:id');
+  console.log('    ✓ Handler registered:', router.routes.has('DELETE /api/users/:id'));
+} catch (e) {
+  console.log('    ❌ router.delete() failed:', e.message);
+}
+
+console.log('\n🔧 Testing Traditional registerRoute() API:');
+
+// Test 6: registerRoute()
+console.log('\n  Test 6: registerRoute()');
+try {
+  router.registerRoute('GET', '/health', (req) => new Response('OK'));
+  console.log('    ✅ registerRoute() works correctly');
+  console.log('    ✓ Route key:', 'GET /health');
+  console.log('    ✓ Handler registered:', router.routes.has('GET /health'));
+} catch (e) {
+  console.log('    ❌ registerRoute() failed:', e.message);
+}
+
+console.log('\n📊 Route Summary:');
+console.log(`   Total routes registered: ${router.routes.size}`);
+console.log('   Registered routes:');
+for (const [key] of router.routes.entries()) {
+  console.log(`      - ${key}`);
+}
+
+console.log('\n' + '='.repeat(60));
+console.log('✨ All tests completed!');
+console.log('\nConclusion:');
+console.log('  ✅ Express-like methods (router.get, router.post, etc.) are now available');
+console.log('  ✅ registerRoute() method still works');
+console.log('  ✅ Both APIs are fully compatible and interchangeable');
+console.log('  ✅ Framework is backward compatible with Express patterns');

package/templates/ai-worker/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "{{SERVICE_NAME}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@tamyla/clodo-framework": "^4.4.1"
+  },
+  "devDependencies": {
+    "wrangler": "^3.0.0",
+    "vitest": "^2.0.0",
+    "@cloudflare/vitest-pool-workers": "^0.5.0"
+  }
+}

package/templates/ai-worker/src/index.js

@@ -0,0 +1,160 @@
+/**
+ * AI Worker Template — @tamyla/clodo-framework
+ * 
+ * A fully working Workers AI service with:
+ * - Text generation (chat/completion)
+ * - Streaming responses (SSE)
+ * - Embeddings generation
+ * - Prompt formatting
+ * - CORS + error handling + rate limiting
+ * 
+ * Deploy with: npx wrangler deploy
+ */
+
+import {
+  createCorsMiddleware,
+  createErrorHandler,
+  createLogger,
+  createRateLimitGuard,
+  composeMiddleware,
+  createEnvironmentGuard
+} from '@tamyla/clodo-framework';
+
+import {
+  AIClient,
+  Models,
+  createSSEStream,
+  streamResponse
+} from '@tamyla/clodo-framework/utilities/ai';
+
+import { formatAIPrompt } from '@tamyla/clodo-framework/utilities';
+
+// ── Environment validation ────────────────────────────────────────────
+const envGuard = createEnvironmentGuard({
+  required: ['AI'],
+  optional: ['KV_DATA', 'VECTORIZE_INDEX']
+});
+
+// ── Middleware stack ──────────────────────────────────────────────────
+const middleware = composeMiddleware(
+  createCorsMiddleware({ origins: ['*'] }),
+  createLogger({ prefix: 'ai-worker', level: 'info' }),
+  createRateLimitGuard({ maxRequests: 50, windowMs: 60000 }),
+  createErrorHandler({ includeStack: false })
+);
+
+// ── Routes ────────────────────────────────────────────────────────────
+const routes = {
+  // Health check
+  'GET /health': async (req, env) => {
+    return jsonResponse({ status: 'healthy', model: Models.CHAT });
+  },
+
+  // Chat completion (non-streaming)
+  'POST /api/chat': async (req, env) => {
+    const { messages, model, max_tokens } = await req.json();
+    const ai = new AIClient(env.AI);
+
+    const response = await ai.chat(messages || [], {
+      model: model || Models.CHAT,
+      max_tokens: max_tokens || 1024
+    });
+
+    return jsonResponse({ response: response.response, model: model || Models.CHAT });
+  },
+
+  // Chat completion (streaming SSE)
+  'POST /api/chat/stream': async (req, env) => {
+    const { messages, model, max_tokens } = await req.json();
+    const ai = new AIClient(env.AI);
+
+    const stream = await ai.run(model || Models.CHAT, {
+      messages: messages || [],
+      max_tokens: max_tokens || 1024,
+      stream: true
+    });
+
+    return streamResponse(stream);
+  },
+
+  // Text generation from prompt template
+  'POST /api/generate': async (req, env) => {
+    const { prompt, context, model, max_tokens } = await req.json();
+    const ai = new AIClient(env.AI);
+
+    // Format the prompt with context variables
+    const formattedPrompt = context ? formatAIPrompt(prompt, context) : prompt;
+
+    const response = await ai.generate(formattedPrompt, {
+      model: model || Models.TEXT_GENERATION,
+      max_tokens: max_tokens || 2048
+    });
+
+    return jsonResponse({ response: response.response, prompt: formattedPrompt });
+  },
+
+  // Generate embeddings
+  'POST /api/embeddings': async (req, env) => {
+    const { text, texts, model } = await req.json();
+    const ai = new AIClient(env.AI);
+
+    const input = texts || [text];
+    const embeddings = await ai.embed(input, {
+      model: model || Models.EMBEDDINGS
+    });
+
+    return jsonResponse({
+      embeddings: embeddings.data,
+      model: model || Models.EMBEDDINGS,
+      dimensions: embeddings.data?.[0]?.length || 0
+    });
+  },
+
+  // Summarize text
+  'POST /api/summarize': async (req, env) => {
+    const { text, max_length } = await req.json();
+    const ai = new AIClient(env.AI);
+
+    const result = await ai.summarize(text, {
+      max_length: max_length || 256
+    });
+
+    return jsonResponse({ summary: result.summary });
+  },
+
+  // List available models
+  'GET /api/models': async (req, env) => {
+    return jsonResponse({
+      models: Object.entries(Models).map(([key, value]) => ({
+        name: key,
+        model: value
+      }))
+    });
+  }
+};
+
+// ── Helpers ───────────────────────────────────────────────────────────
+function jsonResponse(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json' }
+  });
+}
+
+// ── Worker entry point ────────────────────────────────────────────────
+export default {
+  async fetch(request, env, ctx) {
+    envGuard.check(env);
+
+    const url = new URL(request.url);
+    const routeKey = `${request.method} ${url.pathname}`;
+    const handler = routes[routeKey];
+
+    if (!handler) {
+      return jsonResponse({ error: 'Not Found', path: url.pathname }, 404);
+    }
+
+    // Execute through middleware chain
+    return middleware.execute(request, () => handler(request, env, ctx));
+  }
+};

package/templates/cron-worker/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "{{SERVICE_NAME}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@tamyla/clodo-framework": "^4.4.1"
+  },
+  "devDependencies": {
+    "wrangler": "^3.0.0",
+    "vitest": "^2.0.0",
+    "@cloudflare/vitest-pool-workers": "^0.5.0"
+  }
+}