@tamyla/clodo-framework 2.0.4 → 2.0.5

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [2.0.5](https://github.com/tamylaa/clodo-framework/compare/v2.0.4...v2.0.5) (2025-10-11)
+
+
+### Bug Fixes
+
+* include templates directory in published package ([8d5c1ff](https://github.com/tamylaa/clodo-framework/commit/8d5c1ffc6090c35751d926042c784ae9b4d711b1))
+
 ## [2.0.4](https://github.com/tamylaa/clodo-framework/compare/v2.0.3...v2.0.4) (2025-10-11)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tamyla/clodo-framework",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Reusable framework for Clodo-style software architecture on Cloudflare Workers + D1",
   "type": "module",
   "sideEffects": [
@@ -58,6 +58,7 @@
     "bin/service-management",
     "bin/security",
     "bin/shared/config",
+    "templates",
     "docs/README.md",
     "docs/overview.md",
     "docs/SECURITY.md",

package/templates/generic/.env.example

@@ -0,0 +1,37 @@
+# {{SERVICE_DISPLAY_NAME}} Environment Variables
+# Copy this file to .env and configure your values
+
+# Domain Configuration
+DOMAIN_NAME={{SERVICE_NAME}}
+ENVIRONMENT=development
+
+# Cloudflare Configuration (required for deployment)
+CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id
+CLOUDFLARE_ZONE_ID=your-zone-id
+
+# Domain URLs (customize as needed)
+PRODUCTION_DOMAIN=api.{{SERVICE_NAME}}.com
+STAGING_DOMAIN=staging-api.{{SERVICE_NAME}}.com
+DEVELOPMENT_DOMAIN=dev-api.{{SERVICE_NAME}}.com
+
+# Service Configuration
+SERVICE_NAME={{SERVICE_NAME}}
+SERVICE_TYPE={{SERVICE_TYPE}}
+LOG_LEVEL=info
+
+# CORS Configuration
+CORS_ORIGINS=*
+
+# Rate Limiting
+RATE_LIMIT_REQUESTS=100
+RATE_LIMIT_WINDOW_MS=60000
+
+# Metrics and Monitoring
+ENABLE_METRICS=false
+METRICS_ENDPOINT=
+
+# Database Configuration (will be set up during deployment)
+# DATABASE_ID=your-database-id
+
+# Add your custom environment variables below
+# CUSTOM_VAR=value

package/templates/generic/README.md

@@ -0,0 +1,206 @@
+# {{SERVICE_DISPLAY_NAME}}
+
+A Clodo Framework {{SERVICE_TYPE}} service generated on {{CURRENT_DATE}}.
+
+## Overview
+
+This service was created using the Clodo Framework template generator. It includes:
+
+- Domain configuration management
+- Feature flag system
+- Automated deployment scripts
+- Consistent service architecture
+- Cloudflare Workers + D1 integration
+
+## Quick Start
+
+1. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+
+2. **Configure your service:**
+   ```bash
+   npm run setup
+   ```
+   This will guide you through:
+   - Domain configuration
+   - Cloudflare account setup
+   - Feature flag configuration
+
+3. **Start development:**
+   ```bash
+   npm run dev
+   ```
+
+4. **Deploy to production:**
+   ```bash
+   npm run deploy -- --Environment production
+   ```
+
+## Project Structure
+
+```
+src/
+├── config/
+│   ├── domains.js     # Domain and feature configuration
+│   └── features.js    # Service-specific feature definitions
+├── worker/
+│   └── index.js       # Cloudflare Worker entry point
+├── routes/            # Route handlers
+├── services/          # Business logic
+└── utils/             # Utility functions
+
+scripts/               # Deployment and setup scripts
+tests/                 # Test files
+migrations/            # Database migrations
+docs/                  # Documentation
+```
+
+## Configuration
+
+### Domain Configuration (`src/config/domains.js`)
+
+Configure your Cloudflare account, domains, and feature flags:
+
+```javascript
+export const domains = {
+  'your-domain': {
+    name: 'your-domain',
+    accountId: 'your-cloudflare-account-id',
+    zoneId: 'your-zone-id',
+    domains: {
+      production: 'api.yourdomain.com',
+      staging: 'staging-api.yourdomain.com'
+    },
+    features: {
+      // Enable/disable features
+      logging: true,
+      monitoring: true
+    }
+  }
+};
+```
+
+### Environment Variables
+
+Create a `.env` file (copy from `.env.example`):
+
+```bash
+DOMAIN_NAME=your-domain
+ENVIRONMENT=development
+```
+
+## Development
+
+### Available Scripts
+
+- `npm test` - Run test suite
+- `npm run dev` - Start development server
+- `npm run deploy` - Deploy to Cloudflare Workers
+- `npm run setup` - Interactive setup wizard
+- `npm run lint` - Lint code
+- `npm run format` - Format code
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm test -- --watch
+
+# Run specific test file
+npm test -- tests/worker.test.js
+```
+
+### Local Development
+
+```bash
+# Start local development server
+npm run dev
+
+# Access your service at:
+# http://localhost:8787
+```
+
+## Deployment
+
+### Staging Deployment
+
+```bash
+npm run deploy -- --Environment staging
+```
+
+### Production Deployment
+
+```bash
+npm run deploy -- --Environment production
+```
+
+### Custom Deployment
+
+```bash
+# Deploy with custom domain
+npm run deploy -- --DomainName your-custom-domain --Environment production
+
+# Dry run (see what would be deployed)
+npm run deploy -- --DryRun
+```
+
+## Features
+
+This service includes these Clodo Framework features:
+
+- **Domain Configuration**: Centralized configuration management
+- **Feature Flags**: Runtime feature toggling
+- **Worker Integration**: Consistent service initialization
+- **Deployment Automation**: One-command deployment
+- **Health Checks**: Built-in service monitoring
+- **Error Handling**: Comprehensive error management
+
+## API Endpoints
+
+### Health Check
+
+```
+GET /health
+```
+
+Returns service health status and configuration information.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "service": "{{SERVICE_NAME}}",
+  "version": "1.0.0",
+  "features": ["logging", "monitoring"],
+  "domain": "your-domain",
+  "environment": "development"
+}
+```
+
+## Clodo Framework
+
+This service is built on the Clodo Framework v{{FRAMEWORK_VERSION}}. The framework provides:
+
+- **Reusable Components**: Pre-built utilities and patterns
+- **Consistent Architecture**: Standardized service structure
+- **Automated Deployment**: One-command deployment to any environment
+- **Feature Management**: Runtime feature toggling
+- **Cross-Service Communication**: Service registry and communication patterns
+
+Learn more: [Clodo Framework Documentation](../../packages/clodo-framework/README.md)
+
+## Contributing
+
+1. Follow the established code patterns
+2. Add tests for new features
+3. Update documentation as needed
+4. Use the Clodo Framework utilities
+
+## License
+
+MIT License - see LICENSE file for details

package/templates/generic/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "{{SERVICE_NAME}}",
+  "version": "1.0.0",
+  "description": "A Clodo Framework {{SERVICE_TYPE}} service",
+  "main": "src/worker/index.js",
+  "type": "module",
+  "scripts": {
+    "test": "jest",
+    "dev": "wrangler dev",
+    "deploy": "powershell .\\scripts\\deploy.ps1",
+    "setup": "powershell .\\scripts\\setup.ps1",
+    "lint": "eslint src/",
+    "format": "prettier --write src/"
+  },
+  "dependencies": {
+    "@tamyla/clodo-framework": "^1.0.0",
+    "wrangler": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "eslint": "^8.54.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.1.0"
+  },
+  "author": "Generated by Clodo Framework",
+  "license": "MIT"
+}

package/templates/generic/scripts/deploy.ps1

@@ -0,0 +1,2 @@
+# Import and run the Clodo Framework deployment script
+. "$PSScriptRoot\..\..\scripts\deploy-domain.ps1" -DomainName {{SERVICE_NAME}} @args

package/templates/generic/scripts/setup.ps1

@@ -0,0 +1,2 @@
+# Import and run the Clodo Framework setup script
+. "$PSScriptRoot\..\..\scripts\setup-interactive.ps1" -ServiceName {{SERVICE_NAME}} -ServiceType {{SERVICE_TYPE}} @args

package/templates/generic/src/config/domains.js

@@ -0,0 +1,105 @@
+import { createDomainConfigSchema } from '@tamyla/clodo-framework';
+
+/**
+ * Domain configuration for {{SERVICE_DISPLAY_NAME}}
+ *
+ * This file contains domain-specific configuration including:
+ * - Cloudflare account and zone settings
+ * - Domain URLs for different environments
+ * - Feature flags and settings
+ * - Database and service bindings
+ */
+
+export const domains = {
+  '{{SERVICE_NAME}}': {
+    ...createDomainConfigSchema(),
+    name: '{{SERVICE_NAME}}',
+    displayName: '{{SERVICE_DISPLAY_NAME}}',
+    accountId: process.env.CLOUDFLARE_ACCOUNT_ID || '', // Configure in setup
+    zoneId: process.env.CLOUDFLARE_ZONE_ID || '',       // Configure in setup
+    domains: {
+      production: process.env.PRODUCTION_DOMAIN || 'api.{{SERVICE_NAME}}.com',
+      staging: process.env.STAGING_DOMAIN || 'staging-api.{{SERVICE_NAME}}.com',
+      development: process.env.DEVELOPMENT_DOMAIN || 'dev-api.{{SERVICE_NAME}}.com'
+    },
+    services: [
+      '{{SERVICE_NAME}}'
+    ],
+    databases: [
+      {
+        name: '{{SERVICE_NAME}}-db',
+        type: 'd1'
+      }
+    ],
+    features: {
+      // Core features (always enabled)
+      logging: true,
+      monitoring: true,
+      errorReporting: true,
+
+      // Service-specific features (uncomment and modify based on SERVICE_TYPE)
+      // Data service features
+      // authentication: true,
+      // authorization: true,
+      // fileStorage: true,
+      // search: true,
+      // filtering: true,
+      // pagination: true,
+
+      // Auth service features
+      // authentication: true,
+      // authorization: true,
+      // userProfiles: true,
+      // emailNotifications: true,
+      // magicLinkAuth: true,
+
+      // Content service features
+      // fileStorage: true,
+      // search: true,
+      // filtering: true,
+      // pagination: true,
+      // caching: true,
+
+      // API Gateway features
+      // authentication: true,
+      // authorization: true,
+      // rateLimiting: true,
+      // caching: true,
+      // monitoring: true,
+
+      // Generic service features (customize as needed)
+      // authentication: false,
+      // caching: false,
+    },
+    settings: {
+      environment: process.env.ENVIRONMENT || 'development',
+      logLevel: process.env.LOG_LEVEL || 'info',
+      corsOrigins: process.env.CORS_ORIGINS ? process.env.CORS_ORIGINS.split(',') : ['*'],
+      rateLimitRequests: parseInt(process.env.RATE_LIMIT_REQUESTS) || 100,
+      rateLimitWindowMs: parseInt(process.env.RATE_LIMIT_WINDOW_MS) || 60000,
+      enableMetrics: process.env.ENABLE_METRICS === 'true',
+      metricsEndpoint: process.env.METRICS_ENDPOINT
+    }
+  }
+};
+
+/**
+ * Get domain configuration for current environment
+ * @param {string} domainName - Name of the domain
+ * @returns {Object} Domain configuration
+ */
+export function getDomainConfig(domainName = '{{SERVICE_NAME}}') {
+  const config = domains[domainName];
+  if (!config) {
+    throw new Error(`Domain configuration not found: ${domainName}`);
+  }
+  return config;
+}
+
+/**
+ * Get all available domains
+ * @returns {string[]} Array of domain names
+ */
+export function getAvailableDomains() {
+  return Object.keys(domains);
+}

package/templates/generic/src/worker/index.js

@@ -0,0 +1,183 @@
+import { initializeService, createFeatureGuard, COMMON_FEATURES } from '@tamyla/clodo-framework';
+import { domains } from './config/domains.js';
+
+/**
+ * {{SERVICE_DISPLAY_NAME}} - Clodo Framework Service
+ *
+ * Generated on: {{CURRENT_DATE}}
+ * Service Type: {{SERVICE_TYPE}}
+ */
+
+export default {
+  async fetch(request, env, ctx) {
+    try {
+      // Initialize service with Clodo Framework
+      const service = initializeService(env, domains);
+
+      // Log request (if logging is enabled)
+      if (service.features.includes(COMMON_FEATURES.LOGGING)) {
+        console.log(`${request.method} ${request.url} - ${service.domain} (${service.environment})`);
+      }
+
+      const url = new URL(request.url);
+
+      // Health check endpoint
+      if (url.pathname === '/health') {
+        return new Response(JSON.stringify({
+          status: 'healthy',
+          service: '{{SERVICE_NAME}}',
+          version: '1.0.0',
+          type: '{{SERVICE_TYPE}}',
+          features: service.features,
+          domain: service.domain,
+          environment: service.environment,
+          timestamp: new Date().toISOString()
+        }), {
+          headers: {
+            'Content-Type': 'application/json',
+            'Cache-Control': 'no-cache'
+          }
+        });
+      }
+
+      // Service information endpoint
+      if (url.pathname === '/info') {
+        return new Response(JSON.stringify({
+          name: '{{SERVICE_NAME}}',
+          displayName: '{{SERVICE_DISPLAY_NAME}}',
+          type: '{{SERVICE_TYPE}}',
+          version: '1.0.0',
+          framework: 'Clodo Framework',
+          frameworkVersion: '{{FRAMEWORK_VERSION}}',
+          domain: service.domain,
+          environment: service.environment,
+          features: service.features
+        }), {
+          headers: { 'Content-Type': 'application/json' }
+        });
+      }
+
+      // Add your service-specific routes here
+      // Example routes for different service types:
+
+      // Data Service Routes (uncomment and implement for data-service type)
+      // if (url.pathname.startsWith('/api/data')) {
+      //   return handleDataRoutes(request, env, ctx, service);
+      // }
+
+      // Auth Service Routes (uncomment and implement for auth-service type)
+      // if (url.pathname.startsWith('/auth')) {
+      //   return handleAuthRoutes(request, env, ctx, service);
+      // }
+
+      // Content Service Routes (uncomment and implement for content-service type)
+      // if (url.pathname.startsWith('/content')) {
+      //   return handleContentRoutes(request, env, ctx, service);
+      // }
+
+      // API Gateway Routes (uncomment and implement for api-gateway type)
+      // return handleGatewayRoutes(request, env, ctx, service);
+
+      // Default response for unmatched routes
+      return new Response(JSON.stringify({
+        error: 'Not Found',
+        message: 'The requested endpoint does not exist',
+        service: '{{SERVICE_NAME}}',
+        availableEndpoints: [
+          '/health',
+          '/info'
+          // Add your endpoints here
+        ]
+      }), {
+        status: 404,
+        headers: { 'Content-Type': 'application/json' }
+      });
+
+    } catch (error) {
+      console.error('Service error:', error);
+
+      // Return appropriate error response
+      const errorResponse = {
+        error: 'Internal Server Error',
+        message: error.message,
+        service: '{{SERVICE_NAME}}',
+        timestamp: new Date().toISOString()
+      };
+
+      // Include stack trace in development
+      if (env.ENVIRONMENT === 'development') {
+        errorResponse.stack = error.stack;
+      }
+
+      return new Response(JSON.stringify(errorResponse), {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' }
+      });
+    }
+  }
+};
+
+// Placeholder route handlers - implement these based on your service needs
+
+async function handleDataRoutes(request, env, ctx, service) {
+  const url = new URL(request.url);
+
+  switch (request.method) {
+    case 'GET':
+      if (url.pathname === '/api/data') {
+        // Return data list
+        return new Response(JSON.stringify({
+          data: [],
+          message: 'Data endpoint - implement your data retrieval logic'
+        }), {
+          headers: { 'Content-Type': 'application/json' }
+        });
+      }
+      break;
+
+    case 'POST':
+      if (url.pathname === '/api/data') {
+        // Create new data
+        return new Response(JSON.stringify({
+          success: true,
+          message: 'Data creation endpoint - implement your creation logic'
+        }), {
+          status: 201,
+          headers: { 'Content-Type': 'application/json' }
+        });
+      }
+      break;
+  }
+
+  return new Response(JSON.stringify({ error: 'Method not allowed' }), {
+    status: 405,
+    headers: { 'Content-Type': 'application/json' }
+  });
+}
+
+async function handleAuthRoutes(request, env, ctx, service) {
+  // Implement authentication routes
+  return new Response(JSON.stringify({
+    message: 'Auth service - implement authentication logic'
+  }), {
+    headers: { 'Content-Type': 'application/json' }
+  });
+}
+
+async function handleContentRoutes(request, env, ctx, service) {
+  // Implement content management routes
+  return new Response(JSON.stringify({
+    message: 'Content service - implement content management logic'
+  }), {
+    headers: { 'Content-Type': 'application/json' }
+  });
+}
+
+async function handleGatewayRoutes(request, env, ctx, service) {
+  // Implement API gateway logic
+  return new Response(JSON.stringify({
+    message: 'API Gateway - implement routing logic'
+  }), {
+    headers: { 'Content-Type': 'application/json' }
+  });
+}

package/templates/generic/wrangler.toml

@@ -0,0 +1,27 @@
+name = "{{SERVICE_NAME}}-dev"
+main = "src/worker/index.js"
+compatibility_date = "{{CURRENT_DATE}}"
+
+[env.development]
+name = "{{SERVICE_NAME}}-dev"
+
+[env.staging]
+name = "{{SERVICE_NAME}}-staging"
+
+[env.production]
+name = "{{SERVICE_NAME}}"
+
+# Database bindings will be added during deployment
+# [[d1_databases]]
+# binding = "{{SERVICE_NAME}}-db"
+# database_name = "{{SERVICE_NAME}}-db"
+
+# Environment variables
+[vars]
+DOMAIN_NAME = "{{SERVICE_NAME}}.yourdomain.com"
+ENVIRONMENT = "development"
+SERVICE_NAME = "{{SERVICE_NAME}}"
+SERVICE_TYPE = "{{SERVICE_TYPE}}"
+
+# Add your custom environment variables here
+# CUSTOM_VAR = "value"

package/templates/scripts/deploy.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+/**
+ * Cross-platform deployment helper
+ * 
+ * Handles npm config variables properly across Windows, Linux, and Mac.
+ * PowerShell doesn't expand $npm_config_customer, so we use process.env instead.
+ * 
+ * Usage:
+ *   npm run deploy:dev --customer=wetechfounders
+ *   npm run deploy:staging --customer=wetechfounders
+ *   npm run deploy:prod --customer=wetechfounders
+ * 
+ * Or use the framework CLI directly:
+ *   npx clodo-service deploy --customer=wetechfounders --env=development
+ */
+
+import { execSync } from 'child_process';
+
+const environment = process.argv[2] || 'development';
+const customer = process.env.npm_config_customer;
+
+if (!customer) {
+  console.error('❌ Error: Customer name required');
+  console.error('');
+  console.error('Usage:');
+  console.error('  npm run deploy:dev --customer=wetechfounders');
+  console.error('  npm run deploy:staging --customer=greatidude');
+  console.error('  npm run deploy:prod --customer=tamyla');
+  console.error('');
+  console.error('Or use the framework CLI directly:');
+  console.error('  npx clodo-service deploy --customer=wetechfounders --env=development');
+  process.exit(1);
+}
+
+console.log(`🚀 Deploying ${customer} to ${environment}...`);
+
+try {
+  // Use framework CLI (clodo-service has more features than clodo-security)
+  execSync(`npx clodo-service deploy --customer=${customer} --env=${environment}`, {
+    stdio: 'inherit'
+  });
+} catch (error) {
+  process.exit(error.status || 1);
+}