@tamyla/clodo-framework 4.4.0 → 4.5.0

package/docs/api-reference.md

@@ -296,6 +296,40 @@ router.registerRoute('GET', '/api/users/:id', async (request, id) => {
 });
 ```
 
+##### Express-like Convenience Methods
+
+For familiarity with Express patterns, use these shorthand methods:
+
+```javascript
+// GET route
+router.get('/api/users', async (request) => {
+  return new Response(JSON.stringify(users));
+});
+
+// POST route
+router.post('/api/users', async (request) => {
+  const userData = await request.json();
+  return new Response(JSON.stringify(newUser), { status: 201 });
+});
+
+// PUT route
+router.put('/api/users/:id', async (request, id) => {
+  return new Response(JSON.stringify(updatedUser));
+});
+
+// PATCH route
+router.patch('/api/users/:id', async (request, id) => {
+  return new Response(JSON.stringify(patchedUser));
+});
+
+// DELETE route
+router.delete('/api/users/:id', async (request, id) => {
+  return new Response(JSON.stringify({ success: true }));
+});
+```
+
+These methods are aliases to `registerRoute()` and support the same handler signature.
+
 ##### `handleRequest(method, path, request)`
 ```javascript
 const response = await router.handleRequest('GET', '/api/users/123', request);
@@ -441,6 +475,125 @@ const config = DeploymentManager.generateSecureConfig('client', 'prod');
 
 ## ⚙️ Configuration Management
 
+### Service Environment Variables (v4.4.1+)
+
+The framework standardizes how environment variables are configured in services using a single recommended flat format.
+
+#### Recommended Format: Flat Structure
+
+```javascript
+// services-config.json
+{
+  "services": [
+    {
+      "name": "api-service",
+      "vars": {
+        "API_KEY": "my-api-key",
+        "DEBUG": "true",
+        "LOG_LEVEL": "info"
+      },
+      "secrets": ["DB_PASSWORD", "JWT_SECRET"]
+    }
+  ]
+}
+```
+
+**Benefits**:
+- Simple and clear
+- Aligns with Wrangler.toml conventions
+- Type-safe with validation
+- No version-specific migrations needed
+
+#### Variable Naming Conventions
+
+All environment variable names must follow SCREAMING_SNAKE_CASE:
+
+```javascript
+// ✅ Valid
+API_KEY          // Uppercase, underscores
+DATABASE_URL     // Multi-word with underscores
+_INTERNAL_FLAG   // Starting with underscore
+VAR_123          // With numbers
+
+// ❌ Invalid
+api-key          // No hyphens
+api.key          // No dots
+apiKey           // No camelCase
+```
+
+#### Secrets Management
+
+Specify which variables contain sensitive data:
+
+```javascript
+{
+  "services": [
+    {
+      "name": "api-service",
+      "vars": {
+        "API_URL": "https://api.example.com",    // Non-secret
+        "ENVIRONMENT": "production"               // Non-secret
+      },
+      "secrets": ["API_KEY", "DB_PASSWORD"]      // Sensitive values
+    }
+  ]
+}
+```
+
+Then provide secret values at deployment time via environment variables or `.dev.vars` file.
+
+#### Deprecation Notice (v4.4.1+)
+
+The following formats are deprecated and will be removed in v5.0.0:
+
+**Nested Format** (Deprecated):
+```javascript
+// ⚠️ Avoid: Will be removed in v5.0.0
+{
+  "environment": {
+    "vars": { "API_KEY": "value" },
+    "secrets": ["DB_PASSWORD"]
+  }
+}
+```
+
+**Per-Environment Format** (Deprecated):
+```javascript
+// ⚠️ Avoid: Will be removed in v5.0.0
+{
+  "env": {
+    "production": { "vars": { "API_KEY": "prod-key" } },
+    "staging": { "vars": { "API_KEY": "staging-key" } }
+  }
+}
+```
+
+**Migration Path**: See [Environment Variable Standardization Guide](./env-var-standardization.md) for complete migration instructions.
+
+#### Using `EnvironmentVarNormalizer`
+
+The framework provides automatic normalization for backward compatibility:
+
+```javascript
+import { EnvironmentVarNormalizer } from '@tamyla/clodo-framework';
+
+// Normalize any config format to standard flat structure
+const normalized = EnvironmentVarNormalizer.normalize(service, {
+  warnOnDeprecated: true,  // Log deprecation warnings
+  throwOnConflict: false   // Merge conflicting formats
+});
+
+// Validate variable naming conventions
+const validation = EnvironmentVarNormalizer.validateNamingConventions(vars);
+if (!validation.valid) {
+  console.error('Variable naming issues:', validation.issues);
+}
+
+// Check deprecation timeline
+const timeline = EnvironmentVarNormalizer.getDeprecationTimeline('4.4.1');
+console.log(timeline.v5_0_0.status);  // "REMOVAL"
+```
+
 ### Domain Configuration
 
 #### `createDomainConfigSchema(domains)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tamyla/clodo-framework",
-  "version": "4.4.0",
+  "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"
+  }
+}