@tamyla/clodo-framework 4.0.13 → 4.0.15

package/dist/utils/TemplateRuntime.js

@@ -0,0 +1,291 @@
+/**
+ * Template Runtime Coordination
+ * Provides consistent code generation helpers for templates
+ */
+
+/**
+ * Template Runtime for consistent code generation
+ */
+export class TemplateRuntime {
+  /**
+   * Generate consistent binding objects for templates
+   * @param {Object} features - Enabled features configuration
+   * @returns {Object} Binding configuration
+   */
+  static generateBindings(features) {
+    const bindings = {};
+
+    // D1 Database bindings
+    if (features.d1) {
+      bindings.DATABASE = {
+        type: 'd1',
+        id: 'DB'
+      };
+    }
+
+    // KV Namespace bindings
+    if (features.kv) {
+      bindings.KV_CACHE = {
+        type: 'kv_namespace',
+        id: 'CACHE'
+      };
+    }
+
+    // R2 Bucket bindings
+    if (features.r2) {
+      bindings.R2_STORAGE = {
+        type: 'r2_bucket',
+        id: 'STORAGE'
+      };
+    }
+
+    // Durable Object bindings
+    if (features.durableObjects) {
+      bindings.DURABLE_OBJECT = {
+        type: 'durable_object',
+        className: 'MyDurableObject'
+      };
+    }
+
+    // Queue bindings
+    if (features.queue) {
+      bindings.QUEUE = {
+        type: 'queue',
+        queueName: 'my-queue'
+      };
+    }
+
+    // Email bindings
+    if (features.email) {
+      bindings.EMAIL = {
+        type: 'email'
+      };
+    }
+    return bindings;
+  }
+
+  /**
+   * Generate consistent import statements for templates
+   * @param {Object} features - Enabled features configuration
+   * @returns {string[]} Array of import statements
+   */
+  static generateImports(features) {
+    const imports = [];
+
+    // Framework imports
+    imports.push("import { initializeService } from '@tamyla/clodo-framework/worker';");
+
+    // Feature-specific imports
+    if (features.d1) {
+      imports.push("import { D1Database } from '@cloudflare/workers-types';");
+    }
+    if (features.kv) {
+      imports.push("import { KVNamespace } from '@cloudflare/workers-types';");
+    }
+    if (features.r2) {
+      imports.push("import { R2Bucket } from '@cloudflare/workers-types';");
+    }
+    if (features.durableObjects) {
+      imports.push("import { DurableObject } from '@cloudflare/workers-types';");
+    }
+    if (features.queue) {
+      imports.push("import { Queue } from '@cloudflare/workers-types';");
+    }
+    if (features.email) {
+      imports.push("import { EmailMessage } from '@cloudflare/workers-types';");
+    }
+
+    // Utility imports
+    if (features.logging) {
+      imports.push("import { Logger } from '@tamyla/clodo-framework/utils';");
+    }
+    if (features.validation) {
+      imports.push("import { validateRequest } from '@tamyla/clodo-framework/utils';");
+    }
+    return imports;
+  }
+
+  /**
+   * Generate consistent route handlers for templates
+   * @param {Object} routes - Route configuration
+   * @param {Object} features - Enabled features
+   * @returns {string} Generated route handler code
+   */
+  static generateRouteHandlers(routes, features) {
+    let code = '';
+
+    // Generate route handling logic
+    code += 'export async function handleRequest(request, env, ctx) {\n';
+    code += '  const url = new URL(request.url);\n';
+    code += '  const method = request.method;\n\n';
+
+    // Add route matching
+    for (const [path, config] of Object.entries(routes)) {
+      code += `  if (url.pathname === '${path}') {\n`;
+
+      // Method-specific handling
+      if (config.methods && Array.isArray(config.methods)) {
+        code += `    if (${config.methods.map(m => `method === '${m}'`).join(' || ')}) {\n`;
+      }
+
+      // Feature guards
+      if (config.features) {
+        for (const feature of config.features) {
+          code += `      // Check ${feature} feature\n`;
+          code += `      if (!env.FEATURES?.${feature}) {\n`;
+          code += `        return new Response('Feature not enabled', { status: 403 });\n`;
+          code += `      }\n`;
+        }
+      }
+
+      // Handler logic
+      const handlerName = this.capitalize(path.split('/').filter(Boolean).pop());
+      code += `      return await handle${handlerName}(request, env, ctx);\n`;
+      if (config.methods && Array.isArray(config.methods)) {
+        code += `    }\n`;
+      }
+      code += `  }\n\n`;
+    }
+    code += '  return new Response(\'Not Found\', { status: 404 });\n';
+    code += '}\n\n';
+
+    // Generate individual handlers
+    for (const [path] of Object.entries(routes)) {
+      const handlerName = this.capitalize(path.split('/').filter(Boolean).pop());
+      code += `async function handle${handlerName}(request, env, ctx) {\n`;
+      code += `  // TODO: Implement ${handlerName} handler\n`;
+      code += `  return new Response('Hello from ${handlerName}');\n`;
+      code += `}\n\n`;
+    }
+    return code;
+  }
+
+  /**
+   * Generate consistent middleware chain for templates
+   * @param {string[]} middleware - List of middleware names
+   * @returns {string} Generated middleware chain code
+   */
+  static generateMiddlewareChain(middleware) {
+    let code = '';
+    code += 'export function createMiddlewareChain() {\n';
+    code += '  const middlewares = [\n';
+    for (const mw of middleware) {
+      code += `    ${mw},\n`;
+    }
+    code += '  ];\n\n';
+    code += '  return (handler) => {\n';
+    code += '    return middlewares.reduceRight((acc, mw) => mw(acc), handler);\n';
+    code += '  };\n';
+    code += '}\n\n';
+    return code;
+  }
+
+  /**
+   * Generate consistent error handling for templates
+   * @param {Object} features - Enabled features
+   * @returns {string} Generated error handling code
+   */
+  static generateErrorHandling(features) {
+    let code = '';
+    code += 'export function createErrorHandler() {\n';
+    code += '  return async (error, request, env, ctx) => {\n';
+    code += '    console.error(\'Request error:\', error);\n\n';
+    if (features.logging) {
+      code += '    // Log error details\n';
+      code += '    await logError(error, request);\n\n';
+    }
+    code += '    // Return appropriate error response\n';
+    code += '    if (error.status) {\n';
+    code += '      return new Response(JSON.stringify({\n';
+    code += '        error: error.message,\n';
+    code += '        status: error.status\n';
+    code += '      }), {\n';
+    code += '        status: error.status,\n';
+    code += '        headers: { \'Content-Type\': \'application/json\' }\n';
+    code += '      });\n';
+    code += '    }\n\n';
+    code += '    return new Response(JSON.stringify({\n';
+    code += '      error: \'Internal Server Error\',\n';
+    code += '      status: 500\n';
+    code += '    }), {\n';
+    code += '      status: 500,\n';
+    code += '      headers: { \'Content-Type\': \'application/json\' }\n';
+    code += '    });\n';
+    code += '  };\n';
+    code += '}\n\n';
+    return code;
+  }
+
+  /**
+   * Generate consistent health check endpoint for templates
+   * @param {Object} serviceInfo - Service information
+   * @returns {string} Generated health check code
+   */
+  static generateHealthCheck(serviceInfo) {
+    let code = '';
+    code += 'export async function handleHealthCheck(request, env, ctx) {\n';
+    code += '  const health = {\n';
+    code += '    status: \'healthy\',\n';
+    code += `    service: '${serviceInfo.name || 'unknown'}',\n`;
+    code += `    version: '${serviceInfo.version || '1.0.0'}',\n`;
+    code += `    type: '${serviceInfo.type || 'generic'}',\n`;
+    code += '    timestamp: new Date().toISOString(),\n';
+    code += '    checks: {}\n';
+    code += '  };\n\n';
+
+    // Add database health checks
+    if (serviceInfo.features?.d1) {
+      code += '  try {\n';
+      code += '    // Check D1 database connectivity\n';
+      code += '    await env.DATABASE.prepare(\'SELECT 1\').first();\n';
+      code += '    health.checks.database = { status: \'healthy\' };\n';
+      code += '  } catch (error) {\n';
+      code += '    health.checks.database = { status: \'unhealthy\', error: error.message };\n';
+      code += '    health.status = \'unhealthy\';\n';
+      code += '  }\n\n';
+    }
+
+    // Add KV health checks
+    if (serviceInfo.features?.kv) {
+      code += '  try {\n';
+      code += '    // Check KV connectivity\n';
+      code += '    await env.KV_CACHE.put(\'health-check\', \'ok\', { expirationTtl: 60 });\n';
+      code += '    health.checks.kv = { status: \'healthy\' };\n';
+      code += '  } catch (error) {\n';
+      code += '    health.checks.kv = { status: \'unhealthy\', error: error.message };\n';
+      code += '    health.status = \'unhealthy\';\n';
+      code += '  }\n\n';
+    }
+
+    // Add R2 health checks
+    if (serviceInfo.features?.r2) {
+      code += '  try {\n';
+      code += '    // Check R2 bucket connectivity\n';
+      code += '    await env.R2_STORAGE.head(\'health-check.txt\');\n';
+      code += '    health.checks.r2 = { status: \'healthy\' };\n';
+      code += '  } catch (error) {\n';
+      code += '    health.checks.r2 = { status: \'unhealthy\', error: error.message };\n';
+      code += '    health.status = \'unhealthy\';\n';
+      code += '  }\n\n';
+    }
+    code += '  const statusCode = health.status === \'healthy\' ? 200 : 503;\n';
+    code += '  return new Response(JSON.stringify(health), {\n';
+    code += '    status: statusCode,\n';
+    code += '    headers: {\n';
+    code += '      \'Content-Type\': \'application/json\',\n';
+    code += '      \'Cache-Control\': \'no-cache\'\n';
+    code += '    }\n';
+    code += '  });\n';
+    code += '}\n\n';
+    return code;
+  }
+
+  /**
+   * Utility function to capitalize strings
+   * @param {string} str - String to capitalize
+   * @returns {string} Capitalized string
+   */
+  static capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+}

package/dist/utils/deployment/secret-generator.js

@@ -23,15 +23,9 @@ const moduleFileManager = new FileManager({
   enableCache: true
 });
 
-// Handle test environment where import.meta might be transformed
-try {
-  __filename = fileURLToPath(import.meta.url);
-  __dirname = dirname(__filename);
-} catch (error) {
-  // Fallback for test environment
-  __dirname = join(process.cwd(), 'src', 'utils', 'deployment');
-  __filename = join(__dirname, 'secret-generator.js');
-}
+// Set __dirname relative to current working directory for compatibility
+__dirname = join(process.cwd(), 'src', 'utils', 'deployment');
+__filename = join(__dirname, 'secret-generator.js');
 const SECRET_CONFIGS = {
   'AUTH_JWT_SECRET': {
     length: 64,
@@ -104,13 +98,15 @@ export class EnhancedSecretManager {
     this.environmentConfigs = new Map();
     this.rotationSchedule = new Map();
 
-    // Paths for secret management
+    // Persistence opt-in: secrets are sensitive. Default storage is inside .clodo-cache and persistence is disabled
+    this.enablePersistence = options.enablePersistence ?? process.env.CLODO_ENABLE_PERSISTENCE === '1';
+    // Paths for secret management (default to cache to avoid polluting workspace root)
     this.secretPaths = {
-      root: join(this.projectRoot, 'secrets'),
-      distribution: join(this.projectRoot, 'secrets', 'distribution'),
-      backups: join(this.projectRoot, 'secrets', 'backups'),
+      root: join(this.projectRoot, '.clodo-cache', 'secrets'),
+      distribution: join(this.projectRoot, '.clodo-cache', 'secrets', 'distribution'),
+      backups: join(this.projectRoot, '.clodo-cache', 'secrets', 'backups'),
       audit: join(this.projectRoot, 'logs', 'secrets-audit.log'),
-      templates: join(this.projectRoot, 'secrets', 'templates')
+      templates: join(this.projectRoot, '.clodo-cache', 'secrets', 'templates')
     };
 
     // Supported output formats
@@ -158,16 +154,21 @@ export class EnhancedSecretManager {
       console.log('');
     }
 
-    // Create directories
-    Object.values(this.secretPaths).forEach(path => {
-      if (!path.endsWith('.log')) {
-        this.ensureDirectory(path);
-      } else {
-        // For log files, ensure parent directory exists
-        const logDir = dirname(path);
-        this.ensureDirectory(logDir);
-      }
-    });
+    // Create directories only when persistence is explicitly enabled (prevents accidental creation of secrets in workspaces)
+    const shouldCreateDirs = this.enablePersistence && !isTestEnv && !this.dryRun;
+    if (shouldCreateDirs) {
+      Object.values(this.secretPaths).forEach(path => {
+        if (!path.endsWith('.log')) {
+          this.ensureDirectory(path);
+        } else {
+          // For log files, ensure parent directory exists
+          const logDir = dirname(path);
+          this.ensureDirectory(logDir);
+        }
+      });
+    } else {
+      console.log('   ℹ️ Secrets persistence disabled or dry-run/test env: skipping secrets directory creation');
+    }
     this.logSecretEvent('MANAGER_INITIALIZED', 'SYSTEM', {
       formats: Object.keys(this.outputFormats),
       mode: this.dryRun ? 'DRY_RUN' : 'LIVE'
@@ -698,6 +699,10 @@ ${Object.entries(SECRET_CONFIGS).map(([key, config]) => `- **${key}**: ${config.
   }
   async saveDomainSecrets(domain, environment, secretData) {
     const filename = join(this.secretPaths.root, `${domain}-${environment}-secrets.json`);
+    if (!this.enablePersistence) {
+      console.log(`   ℹ️ Persistence disabled: not saving secrets to disk for ${domain} (${environment})`);
+      return null;
+    }
     if (this.dryRun) {
       console.log(`   🔍 DRY RUN: Would save secrets to ${filename}`);
       return filename;
@@ -753,7 +758,12 @@ export function generateSingleSecret(length = 32) {
   return randomBytes(length / 2).toString('hex');
 }
 export function saveSecrets(domain, environment, secrets, additionalData = {}) {
-  const secretsDir = 'secrets';
+  const secretsDir = process.env.CLODO_SECRETS_DIR || '.clodo-cache/secrets';
+  const persistenceEnabled = process.env.CLODO_ENABLE_PERSISTENCE === '1';
+  if (!persistenceEnabled) {
+    console.log('   ℹ️ Secrets persistence disabled: saveSecrets will not write files unless CLODO_ENABLE_PERSISTENCE=1 is set.');
+    return null;
+  }
   if (!moduleFileManager.exists(secretsDir)) {
     moduleFileManager.ensureDir(secretsDir);
   }
@@ -798,7 +808,8 @@ export function loadSecrets(domain) {
   }
 }
 export function distributeSecrets(domain, secrets) {
-  const distDir = join('secrets', 'distribution', domain);
+  const distBase = process.env.CLODO_SECRETS_DIR || '.clodo-cache/secrets';
+  const distDir = join(distBase, 'distribution', domain);
   moduleFileManager.ensureDir(distDir);
   const files = {};
 

package/dist/version/FrameworkInfo.js

@@ -0,0 +1,104 @@
+/**
+ * Framework Info Module
+ * Provides version detection and framework information
+ */
+
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Framework Information and Version Detection
+ */
+export class FrameworkInfo {
+  /**
+   * Get the current framework version from the consuming service's package.json
+   * @param {string} serviceRoot - Root directory of the consuming service (optional)
+   * @returns {string} Framework version or 'unknown' if not found
+   */
+  static getVersion(serviceRoot = null) {
+    try {
+      // Try to find package.json in the consuming service
+      const searchPaths = [serviceRoot, process.cwd(), resolve(process.cwd(), '..'), resolve(process.cwd(), '../..')].filter(Boolean);
+      for (const searchPath of searchPaths) {
+        try {
+          const packagePath = resolve(searchPath, 'package.json');
+          const packageContent = readFileSync(packagePath, 'utf8');
+          const packageJson = JSON.parse(packageContent);
+
+          // Check for the framework dependency
+          const frameworkDep = packageJson.dependencies?.['@tamyla/clodo-framework'] || packageJson.devDependencies?.['@tamyla/clodo-framework'];
+          if (frameworkDep) {
+            // Extract version from semver range (e.g., "^4.0.11" -> "4.0.11", ">=4.0.0" -> "4.0.0")
+            const version = frameworkDep.replace(/^[^\d]*/, '').split(/[\s-]/)[0];
+            return version || frameworkDep;
+          }
+        } catch (error) {
+          // Continue searching other paths
+          continue;
+        }
+      }
+
+      // Fallback: try to get version from the framework's own package.json
+      try {
+        const frameworkPackagePath = resolve(__dirname, '../../package.json');
+        const frameworkPackage = JSON.parse(readFileSync(frameworkPackagePath, 'utf8'));
+        return frameworkPackage.version || 'unknown';
+      } catch (error) {
+        return 'unknown';
+      }
+    } catch (error) {
+      console.warn('Framework version detection failed:', error.message);
+      return 'unknown';
+    }
+  }
+
+  /**
+   * Get detailed framework information
+   * @param {string} serviceRoot - Root directory of the consuming service (optional)
+   * @returns {Object} Framework information object
+   */
+  static getInfo(serviceRoot = null) {
+    const version = this.getVersion(serviceRoot);
+    return {
+      name: '@tamyla/clodo-framework',
+      version: version,
+      detected: version !== 'unknown',
+      timestamp: new Date().toISOString(),
+      environment: {
+        node: process.version,
+        platform: process.platform,
+        arch: process.arch
+      }
+    };
+  }
+
+  /**
+   * Check if the current version meets minimum requirements
+   * @param {string} minVersion - Minimum required version
+   * @param {string} serviceRoot - Root directory of the consuming service (optional)
+   * @returns {boolean} True if version meets requirements
+   */
+  static meetsMinimumVersion(minVersion, serviceRoot = null) {
+    const currentVersion = this.getVersion(serviceRoot);
+    if (currentVersion === 'unknown') {
+      return false;
+    }
+    try {
+      const current = currentVersion.split('.').map(Number);
+      const minimum = minVersion.split('.').map(Number);
+      for (let i = 0; i < Math.max(current.length, minimum.length); i++) {
+        const currentPart = current[i] || 0;
+        const minimumPart = minimum[i] || 0;
+        if (currentPart > minimumPart) return true;
+        if (currentPart < minimumPart) return false;
+      }
+      return true; // versions are equal
+    } catch (error) {
+      console.warn('Version comparison failed:', error.message);
+      return false;
+    }
+  }
+}

package/dist/worker/integration.js

@@ -3,6 +3,13 @@ import { getDomainFromEnv, createEnvironmentConfig } from '../config/domains.js'
 // Import COMMON_FEATURES from worker-safe constants (no Node.js dependencies)
 import { COMMON_FEATURES } from './features.js';
 
+// Import new framework components (worker-safe only)
+import { FrameworkInfo } from '../version/FrameworkInfo.js';
+import { EnvironmentValidator } from '../utils/EnvironmentValidator.js';
+import { ServiceClient } from '../services/ServiceClient.js';
+import { HealthChecker } from '../monitoring/HealthChecker.js';
+// Note: ConfigurationValidator requires Node.js APIs, so it's not included in worker runtime
+
 // Re-export COMMON_FEATURES for use in worker templates
 export { COMMON_FEATURES };
 
@@ -58,7 +65,12 @@ export const initializeService = (env, domainConfigs = {}) => {
       env,
       isProduction: environment === 'production',
       isStaging: environment === 'staging',
-      isDevelopment: environment === 'development'
+      isDevelopment: environment === 'development',
+      // Enhanced framework features (worker-safe only)
+      serviceClient: new ServiceClient(),
+      healthChecker: new HealthChecker(),
+      environmentValidator: EnvironmentValidator,
+      frameworkInfo: FrameworkInfo.getInfo()
     };
     logger.info(`Service initialized: ${domainConfig.name} (${environment})`);
     logger.debug(`Enabled features: ${serviceContext.features.join(', ')}`);

package/docs/MIDDLEWARE_MIGRATION_SUMMARY.md

@@ -0,0 +1,121 @@
+# Middleware Architecture Migration Summary (v4.1)
+
+## 📌 Purpose
+This document captures the design decisions, implementation details, assumptions, tests, migration steps, and next actions for the contract-first middleware migration (v4.1): moving from per-service concrete middleware implementations (`createServiceMiddleware`) to lightweight middleware contracts with a shared runtime (Registry + Composer).
+
+---
+
+## 🔧 What was implemented
+- Default approach: **contract-first** middleware generation with opt-in `legacy` strategy.
+- New runtime primitives (framework-level):
+  - `src/middleware/Registry.js` - central registry API used in tests and tooling.
+  - `src/middleware/Composer.js` - middleware composer that executes middleware chains with short-circuiting and post-processing.
+  - `src/middleware/types.d.ts` - TypeScript types describing `IServiceMiddleware` and `IMiddlewareChain`.
+  - `src/middleware/shared/` - framework shared middleware: `cors`, `logging`, `basicAuth` (exports in `index.js`).
+- Generator changes:
+  - `ServiceMiddlewareGenerator` now emits either:
+    - A minimal contract class + `registerMiddleware` helper (contract strategy), or
+    - A legacy `createServiceMiddleware` factory (legacy strategy).
+  - Generator also emits a self-contained `src/middleware/runtime.js` and a `src/middleware/shared/` folder when generating services (for self-containment).
+- Worker entry updates:
+  - `WorkerIndexGenerator` updated to import middleware runtime and compose pipeline using `MiddlewareComposer` + `MiddlewareRegistry`.
+  - Worker fetch runtime supports both contract registration and legacy factory via an adapter.
+- Migration tools & tests:
+  - `scripts/migration/migrate-middleware-legacy-to-contract.js` (basic codemod to convert legacy factories to contract skeletons + `registerMiddleware`).
+  - Unit tests added for `Registry`, `Composer`, `shared/cors`, generator outputs, and migration script.
+- CLI:
+  - `cli/commands/create.js` adds `--middleware-strategy <strategy>` CLI flag (default `contract`).
+- Docs & changelog updated:
+  - `docs/HOWTO_CONSUME_CLODO_FRAMEWORK.md` updated to describe the new approach.
+  - `CHANGELOG.md` mentions the v4.1 middleware architecture change.
+
+---
+
+## ✅ Files added / modified (high-level)
+- Added:
+  - `src/middleware/Registry.js`
+  - `src/middleware/Composer.js`
+  - `src/middleware/types.d.ts`
+  - `src/middleware/shared/{cors.js,logging.js,basicAuth.js,index.js}`
+  - `scripts/migration/migrate-middleware-legacy-to-contract.js`
+  - `docs/MIDDLEWARE_MIGRATION_SUMMARY.md` (this file)
+  - Tests: `test/utils/middleware/{Registry,Composer,cors}.test.js`, generator tests and migration test
+- Modified (generators & templates):
+  - `src/service-management/generators/code/ServiceMiddlewareGenerator.js` (now emits contract or legacy output and service-local runtime/shared stubs)
+  - `src/service-management/generators/code/WorkerIndexGenerator.js` (loads middleware using dynamic import and composes pipeline; includes legacy adapter)
+  - `src/service-management/GenerationEngine.js` (passes `middlewareStrategy` through context)
+  - `src/service-management/ServiceOrchestrator.js` & `src/simple-api.js` (accept middleware strategy)
+  - `cli/commands/create.js` (new `--middleware-strategy` option)
+
+---
+
+## 🧭 Key assumptions made
+1. Default strategy is `contract` (opt-in `legacy`).
+2. Generated services are self-contained by default (runtime + shared stubs added into generated service) to work standalone.
+3. Legacy factory shape expected to return object with `processRequest(request)` and `processResponse(response)` methods.
+4. Runtime dynamic import is acceptable in Worker code (`await import('../middleware/service-middleware.js')`).
+5. TypeScript users will later add TS skeletons or `.d.ts` files if they require compile-time checks.
+
+If any of these assumptions are not desirable for your environment, they require small changes (see "Nuances and review points").
+
+---
+
+## ⚠️ Nuances & review points (actionable)
+- Registry duplication:
+  - There are both framework-level `Registry.js` and a service-local `runtime.js` (generated by the generator). Decide whether you want a single shared runtime or per-service runtime. If you prefer a single runtime, update the generator to import the framework runtime rather than generate a local copy.
+- Bundler behavior & dynamic imports:
+  - The dynamic import pattern must be tested with your bundler (esbuild/wrangler). Ensure bundler includes generated middleware files in the built artifact.
+- Adapter coverage:
+  - The legacy adapter covers the common `createServiceMiddleware` factory shape. If your legacy services used other shapes, extend the adapter logic accordingly.
+- TypeScript support:
+  - Generated skeletons are JavaScript; if you primarily use TypeScript, consider adding `.ts` templates and `.d.ts` exports for better DX.
+- Migration tool limitations:
+  - The codemod is intentionally conservative and may require manual editing for complex legacy middleware logic.
+- Security/logging:
+  - The example `logging` middleware uses `console.log` directly—avoid logging sensitive headers. Consider adding redaction configuration.
+
+---
+
+## 🔁 Migration steps (recommended)
+1. Try generating a new service with default (contract) strategy to validate the new flow:
+   - `npx clodo-service create --middleware-strategy contract` (or omit flag — default is `contract`).
+2. To generate an old-style output for a single new service for comparison: `npx clodo-service create --middleware-strategy legacy`.
+3. For existing services using legacy middleware:
+   - Run `node scripts/migration/migrate-middleware-legacy-to-contract.js <servicePath> [serviceName]`.
+   - Review the converted skeleton and verify imports and custom logic—make adjustments as required.
+4. Update tests and CI to include a smoke test that deploys/loads the generated service (both contract and legacy flows).
+
+---
+
+## ✅ Tests & QA to add (if not already present)
+- Integration tests that:
+  - Generate a service with `contract` strategy and verify `registerMiddleware` is invoked and runtime pipeline executes correctly.
+  - Generate a service with `legacy` strategy and verify the legacy adapter path executes `createServiceMiddleware`.
+- Bundle-size smoke test that measures the generated artifact size between legacy and contract strategies.
+- Migration tests on representative real-world legacy middleware shapes.
+
+---
+
+## 📋 Next steps & open todos
+- Complete migration of tests and e2e fixtures that currently rely on legacy middleware.
+- Add TypeScript skeleton templates (optional, recommended for TS-first projects).
+- Decide on runtime model: service-local runtime (current) vs centralized runtime (change generator behavior if you prefer central runtime).
+- Add more robust adapter patterns if you encounter edge-case legacy middleware shapes in the wild.
+
+---
+
+## 📎 Helpful quick references
+- Generator: `src/service-management/generators/code/ServiceMiddlewareGenerator.js`
+- Worker: `src/service-management/generators/code/WorkerIndexGenerator.js`
+- Migration: `scripts/migration/migrate-middleware-legacy-to-contract.js`
+- Runtime: `src/middleware/{Registry.js,Composer.js}`
+- Tests: `test/utils/middleware/*`, `test/service-management/generators/*`, `test/scripts/migration/*`
+
+---
+
+If you'd like, I can now:
+- Finish updating tests/fixtures and add the bundle-size smoke test, or
+- Add TypeScript templates for generated services, or
+- Replace per-service runtime with a centralized runtime (if you prefer that model).
+
+Pick one of the bullets above and I’ll proceed. If you'd like further edits to this summary, I can fold them into this document.