@tamyla/clodo-framework 4.0.13 → 4.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tamyla/clodo-framework",
-  "version": "4.0.13",
+  "version": "4.0.15",
   "description": "Reusable framework for Clodo-style software architecture on Cloudflare Workers + D1",
   "type": "module",
   "sideEffects": [
@@ -31,6 +31,7 @@
     "./security/cli": "./dist/security/SecurityCLI.js",
     "./service-management": "./dist/service-management/index.js",
     "./service-management/create": "./dist/service-management/ServiceCreator.js",
+    "./middleware": "./dist/middleware/index.js",
     "./modules/security": "./dist/modules/security.js"
   },
   "bin": {
@@ -51,6 +52,8 @@
     "docs/overview.md",
     "docs/SECURITY.md",
     "docs/api-reference.md",
+    "docs/MIDDLEWARE_MIGRATION_SUMMARY.md",
+    "scripts",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -69,6 +72,8 @@
     "test:unit": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
+    "test:ci-core": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --runInBand test/templates test/orchestration test/utils --verbose",
+    "test:full": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --config jest.full.config.js --runInBand --verbose",
     "test:cli": "cross-env NODE_OPTIONS=--experimental-vm-modules jest test/cli-integration/ --verbose",
     "test:cli-integration": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --config test/cli-integration/jest.config.js",
     "test:cli-create": "cross-env NODE_OPTIONS=--experimental-vm-modules jest test/cli-integration/clodo-create-service.test.js",
@@ -102,6 +107,8 @@
     "check:imports": "node scripts/utilities/check-import-paths.js",
     "check:dist-imports": "node scripts/utilities/check-dist-imports.js",
     "check:all": "npm run type-check && npm run test",
+    "check:templates": "node scripts/check-templates.js",
+    "ci:validate": "npm run build && npm run check:templates && npm run lint",
     "diagnose": "node scripts/framework-diagnostic.js",
     "analyze:bundle": "echo 'Bundle analysis not implemented yet'",
     "docs": "echo 'JSDoc documentation generation not configured yet'",

package/scripts/DEPLOY_COMMAND_NEW.js

@@ -0,0 +1,128 @@
+// Deploy command - Smart minimal input for service projects only
+import { program } from 'commander';
+import chalk from 'chalk';
+import { join } from 'path';
+
+program
+  .command('deploy')
+  .description('Deploy a Clodo Framework service to Cloudflare Workers')
+  .option('-e, --env <environment>', 'Target environment (development, staging, production)')
+  .option('--token <token>', 'Cloudflare API token (uses CLOUDFLARE_API_TOKEN env var if not provided)')
+  .option('--account-id <id>', 'Cloudflare account ID (uses CLOUDFLARE_ACCOUNT_ID env var if not provided)')
+  .option('--zone-id <id>', 'Cloudflare zone ID (auto-discovered if not provided)')
+  .option('--dry-run', 'Simulate deployment without making changes')
+  .action(async (options) => {
+    try {
+      const { readFileSync, existsSync } = await import('fs');
+      
+      console.log(chalk.cyan('\n🚀 Clodo Service Deployment'));
+      console.log(chalk.gray('─'.repeat(60)));
+      
+      // ===== STEP 1: SERVICE DETECTION =====
+      // Check if this is a Clodo service project (has clodo-service-manifest.json)
+      const manifestPath = join(process.cwd(), 'clodo-service-manifest.json');
+      
+      if (!existsSync(manifestPath)) {
+        console.error(chalk.red('\n❌ Not a Clodo Framework service project!\n'));
+        console.error(chalk.white('This command must be run from within a service created by the framework.\n'));
+        console.error(chalk.yellow('To create a new service:\n'));
+        console.error(chalk.white('  npx @tamyla/clodo-framework create\n'));
+        console.error(chalk.cyan('To deploy an existing service:\n'));
+        console.error(chalk.white('  1. cd into your service project directory\n'));
+        console.error(chalk.white('  2. Set Cloudflare credentials:\n'));
+        console.error(chalk.white('     export CLOUDFLARE_API_TOKEN=your_token\n'));
+        console.error(chalk.white('     export CLOUDFLARE_ACCOUNT_ID=your_account_id\n'));
+        console.error(chalk.white('  3. Run: npx clodo-service deploy --env production\n'));
+        process.exit(1);
+      }
+      
+      let manifest;
+      try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      } catch (err) {
+        console.error(chalk.red(`\n❌ Invalid service manifest: ${err.message}\n`));
+        process.exit(1);
+      }
+      
+      console.log(chalk.green(`✅ Service detected: ${chalk.bold(manifest.serviceName)}`));
+      console.log(chalk.white(`   Type:      ${manifest.serviceType}`));
+      console.log(chalk.white(`   Framework: ${manifest.framework}\n`));
+      
+      // ===== STEP 2: SMART CREDENTIAL GATHERING =====
+      // Gather credentials: from flags > env vars > ask if missing
+      console.log(chalk.cyan('📋 Gathering Deployment Credentials'));
+      console.log(chalk.gray('─'.repeat(60)));
+      
+      // Get environment: from flag > manifest > default to production
+      const environment = options.env || manifest.configuration?.environment || 'production';
+      console.log(chalk.white(`Target environment: ${chalk.bold(environment)}`));
+      
+      // Get Cloudflare token: from flag > env var
+      let token = options.token || process.env.CLOUDFLARE_API_TOKEN;
+      if (!token) {
+        console.error(chalk.red('\n❌ Cloudflare API token required\n'));
+        console.error(chalk.white('Provide via:\n'));
+        console.error(chalk.white('  • Command: npx clodo-service deploy --token <token>\n'));
+        console.error(chalk.white('  • Environment: export CLOUDFLARE_API_TOKEN=<token>\n'));
+        process.exit(1);
+      }
+      console.log(chalk.green(`✅ Cloudflare token: ${token.substring(0, 20)}...`));
+      
+      // Get Cloudflare account ID: from flag > env var
+      let accountId = options.accountId || process.env.CLOUDFLARE_ACCOUNT_ID;
+      if (!accountId) {
+        console.error(chalk.red('\n❌ Cloudflare account ID required\n'));
+        console.error(chalk.white('Provide via:\n'));
+        console.error(chalk.white('  • Command: npx clodo-service deploy --account-id <id>\n'));
+        console.error(chalk.white('  • Environment: export CLOUDFLARE_ACCOUNT_ID=<id>\n'));
+        process.exit(1);
+      }
+      console.log(chalk.green(`✅ Account ID: ${accountId.substring(0, 8)}...`));
+      
+      // Get Cloudflare zone ID: from flag > env var (can be auto-discovered later)
+      let zoneId = options.zoneId || process.env.CLOUDFLARE_ZONE_ID;
+      if (zoneId) {
+        console.log(chalk.green(`✅ Zone ID: ${zoneId.substring(0, 8)}...`));
+      } else {
+        console.log(chalk.yellow('⚠️  Zone ID: Will be auto-discovered from domain'));
+      }
+      
+      // Set environment variables for downstream components
+      process.env.CLOUDFLARE_API_TOKEN = token;
+      process.env.CLOUDFLARE_ACCOUNT_ID = accountId;
+      if (zoneId) {
+        process.env.CLOUDFLARE_ZONE_ID = zoneId;
+      }
+      
+      console.log(chalk.gray('─'.repeat(60)));
+      
+      // ===== STEP 3: INTEGRATION WITH MODULAR DEPLOYER =====
+      // TODO: Import and call ModularEnterpriseDeployer here
+      // For now, show what would happen
+      
+      console.log(chalk.cyan('\n📋 Deployment Plan:'));
+      console.log(chalk.white(`   Service:      ${manifest.serviceName}`));
+      console.log(chalk.white(`   Type:         ${manifest.serviceType}`));
+      console.log(chalk.white(`   Environment:  ${environment}`));
+      console.log(chalk.white(`   Account:      ${accountId.substring(0, 8)}...`));
+      
+      if (options.dryRun) {
+        console.log(chalk.yellow('\n✅ Dry run complete - deployment validated\n'));
+      } else {
+        console.log(chalk.yellow('\n⚠️  Deployment integration with modular deployer pending'));
+        console.log(chalk.white('   See: DEPLOYMENT_SYSTEMS_ANALYSIS.md for architecture\n'));
+      }
+      
+      console.log(chalk.green('✅ Deployment preparation complete\n'));
+      
+    } catch (error) {
+      console.error(chalk.red(`\n❌ Deployment failed: ${error.message}\n`));
+      
+      if (process.env.DEBUG) {
+        console.error(chalk.gray('Stack trace:'));
+        console.error(chalk.gray(error.stack));
+      }
+      
+      process.exit(1);
+    }
+  });

package/scripts/README-automated-testing-suite.md

@@ -0,0 +1,356 @@
+# Clodo Framework Automated Testing Suite
+
+A comprehensive automated testing system for the entire clodo-framework that tests all CLI commands, deployment processes, service lifecycle, integrations, performance, and prevents regressions.
+
+## Overview
+
+The automated testing suite provides systematic testing across multiple categories with **comprehensive coverage of the `clodo-service deploy` command's 3-level input processing**:
+
+- **CLI Tests**: All `clodo-service` commands and help systems
+- **Deployment Tests**: Complete `clodo-service deploy` command validation (Service Detection → Credential Gathering → Configuration Extraction)
+- **Lifecycle Tests**: Complete service create → validate → deploy → update cycle
+- **Integration Tests**: Cross-component functionality and build processes
+- **Performance Tests**: Build and test execution timing
+- **Regression Tests**: Prevention of known issues
+
+## Quick Start
+
+```bash
+# Run all tests (recommended)
+node scripts/automated-testing-suite.js
+
+# Run specific test categories
+node scripts/automated-testing-suite.js cli deployment
+
+# Run with verbose output
+node scripts/automated-testing-suite.js --verbose
+
+# Run only CLI tests
+node scripts/automated-testing-suite.js cli
+```
+
+## Test Categories
+
+### CLI Tests (`cli`)
+Tests all command-line interface functionality:
+- Help commands and usage information
+- Command availability and error handling
+- Option parsing and validation
+
+### Deployment Tests (`deployment`)
+Comprehensive testing of the `clodo-service deploy` command covering all **3 levels of input processing**:
+
+#### Level 1: Service Detection
+- Validates presence of `clodo-service-manifest.json`
+- Tests error handling when manifest is missing
+- Verifies service type and configuration detection
+
+#### Level 2: Credential Gathering
+- Tests credential priority: command flags → environment variables → failure
+- Validates credential validation and error messages
+- Tests different credential input methods (flags, env vars)
+
+#### Level 3: Configuration Extraction
+- Tests manifest parsing and configuration extraction
+- Validates domain, environment, and deployment settings
+- Tests deployment plan generation and validation
+
+**Test Coverage**: 8 deployment tests including real service manifests, credential scenarios, and error conditions.
+
+### Lifecycle Tests (`lifecycle`)
+Tests complete service lifecycle:
+- Service creation with different types
+- Service validation
+- Deployment dry-run testing
+- Service updates and management
+
+### Integration Tests (`integration`)
+Tests cross-component functionality:
+- Full npm test suite execution
+- Build and type checking
+- Linting and unit test integration
+- Dependency validation
+
+### Performance Tests (`performance`)
+Measures system performance:
+- Build execution time
+- Test suite performance
+- Resource usage monitoring
+
+### Regression Tests (`regression`)
+Prevents known issues from reoccurring:
+- Missing dependency detection
+- Build completeness validation
+- CLI command availability
+- Framework integrity checks
+
+## Command Line Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--test-dir <path>` | Directory for test artifacts | `./test-automation` |
+| `--verbose` | Detailed logging and output | `false` |
+| `--no-clean` | Keep test artifacts after run | `false` (cleans by default) |
+| `--parallel` | Run tests in parallel | `false` (future feature) |
+| `--categories <list>` | Comma-separated categories | `all` |
+| `--timeout <ms>` | Individual test timeout | `300000` (5 minutes) |
+| `--help` | Show help message | - |
+
+## Usage Examples
+
+### Development Testing
+```bash
+# Quick CLI validation during development
+node scripts/automated-testing-suite.js cli --verbose
+
+# Test deployment logic
+node scripts/automated-testing-suite.js deployment
+
+# Full integration test
+node scripts/automated-testing-suite.js integration
+```
+
+### CI/CD Integration
+```bash
+# Run all tests in CI environment
+node scripts/automated-testing-suite.js --verbose --no-clean
+
+# Quick smoke test for PR validation
+node scripts/automated-testing-suite.js cli deployment --timeout 60000
+
+# Performance regression testing
+node scripts/automated-testing-suite.js performance
+```
+
+### Debugging and Investigation
+```bash
+# Isolate failing tests
+node scripts/automated-testing-suite.js cli --verbose
+
+# Test specific functionality
+node scripts/automated-testing-suite.js lifecycle --test-dir ./debug-tests
+
+# Full diagnostic run
+node scripts/automated-testing-suite.js all --verbose --no-clean
+```
+
+## Test Output and Reports
+
+### Console Output
+The suite provides real-time feedback:
+```
+[14:23:15] 🚀 Starting Clodo Framework Automated Testing Suite
+[14:23:15] 🧪 Test Directory: C:\path\to\test-automation
+[14:23:15] 🧪 Categories: all
+[14:23:15] 🧪 Parallel Execution: false
+
+[14:23:15] 🚀 Running CLI Command Tests
+[14:23:15] 🧪 Running: clodo-service --help
+[14:23:15] ✅ clodo-service --help (45ms)
+[14:23:15] 🧪 Running: clodo-service list-types
+[14:23:15] ✅ clodo-service list-types (23ms)
+...
+[14:23:20] 🎉 Automated Testing Suite Complete
+
+📊 Test Summary:
+  Total Tests: 24
+  Passed: 22
+  Failed: 2
+  Skipped: 0
+  Duration: 4521ms
+
+📋 Category Results:
+  cli: ✅ 5/5 passed
+  deployment: ✅ 4/4 passed
+  lifecycle: ❌ 2/3 passed
+  integration: ✅ 3/3 passed
+  performance: ✅ 2/2 passed
+  regression: ✅ 4/4 passed
+```
+
+### Detailed Report
+A JSON report is automatically saved to `test-automation/test-report.json`:
+```json
+{
+  "timestamp": "2025-10-27T14:23:20.000Z",
+  "summary": {
+    "total": 24,
+    "passed": 22,
+    "failed": 2,
+    "skipped": 0,
+    "duration": 4521
+  },
+  "categories": {
+    "cli": {
+      "tests": [...],
+      "passed": 5,
+      "failed": 0
+    }
+  },
+  "failures": [...],
+  "options": {...},
+  "environment": {...}
+}
+```
+
+## Test Environment
+
+### Automatic Setup
+- Creates isolated test directory (`./test-automation` by default)
+- Builds framework if needed
+- Manages temporary test services
+- Cleans up after completion (unless `--no-clean`)
+
+### Test Isolation
+- Each test runs in clean environment
+- Temporary services are tracked and removed
+- No interference with development environment
+- Safe for parallel development
+
+## Integration with Development Workflow
+
+### Pre-commit Hooks
+```bash
+# Add to package.json scripts
+"pre-commit": "node scripts/automated-testing-suite.js cli --timeout 30000"
+```
+
+### CI/CD Pipeline
+```yaml
+# GitHub Actions example
+- name: Run Automated Tests
+  run: node scripts/automated-testing-suite.js --verbose --no-clean
+
+- name: Upload Test Results
+  uses: actions/upload-artifact@v3
+  with:
+    name: test-results
+    path: test-automation/
+```
+
+### Development Scripts
+```json
+{
+  "scripts": {
+    "test:automated": "node scripts/automated-testing-suite.js",
+    "test:cli": "node scripts/automated-testing-suite.js cli",
+    "test:deployment": "node scripts/automated-testing-suite.js deployment",
+    "test:smoke": "node scripts/automated-testing-suite.js cli deployment --timeout 30000"
+  }
+}
+```
+
+## Extending the Test Suite
+
+### Adding New Test Categories
+```javascript
+async runCustomTests() {
+  this.log('Running Custom Tests', 'phase');
+  const category = 'custom';
+  this.testResults.categories[category] = { tests: [], passed: 0, failed: 0 };
+
+  const customTests = [
+    {
+      name: 'my-custom-test',
+      command: 'node my-custom-test.js',
+      expectSuccess: true,
+      description: 'Custom test description'
+    }
+  ];
+
+  for (const test of customTests) {
+    await this.runIndividualTest(category, test);
+  }
+}
+```
+
+### Adding New Tests to Existing Categories
+```javascript
+const cliTests = [
+  // existing tests...
+  {
+    name: 'new-cli-command',
+    command: 'node bin/clodo-service.js new-command --help',
+    expectSuccess: true,
+    description: 'Test new CLI command'
+  }
+];
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Tests timing out**
+- Increase timeout: `--timeout 600000`
+- Check for hanging processes
+- Run individual categories to isolate
+
+**Permission errors**
+- Ensure script has execute permissions
+- Check file system permissions for test directory
+- Run as appropriate user
+
+**Build failures in tests**
+- Ensure dependencies are installed: `npm install`
+- Check Node.js version compatibility
+- Verify build scripts in package.json
+
+**Test directory conflicts**
+- Use `--test-dir ./custom-test-dir`
+- Remove conflicting directories manually
+- Use `--no-clean` to preserve for debugging
+
+### Debugging Failed Tests
+```bash
+# Run with maximum verbosity
+node scripts/automated-testing-suite.js --verbose --no-clean
+
+# Test individual categories
+node scripts/automated-testing-suite.js cli --verbose
+
+# Check detailed report
+cat test-automation/test-report.json | jq '.failures'
+```
+
+## Performance Considerations
+
+### Test Execution Time
+- **Full suite**: ~3-5 minutes
+- **CLI only**: ~30 seconds
+- **Individual categories**: ~1-2 minutes
+
+### Resource Usage
+- **Memory**: ~100-200MB peak
+- **Disk**: ~50-100MB for test artifacts
+- **Network**: Minimal (mock deployments)
+
+### Optimization Tips
+- Run specific categories for faster feedback
+- Use `--no-clean` during development
+- Parallel execution support (future feature)
+- CI caching for dependencies
+
+## Related Files
+
+- `scripts/test-clodo-deployment.js` - Individual deployment testing
+- `test/` - Unit and integration tests
+- `package.json` - Test scripts and configuration
+- `jest.config.js` - Test framework configuration
+
+## Contributing
+
+When adding new functionality:
+1. Add corresponding tests to the automated suite
+2. Update this documentation
+3. Ensure tests pass in CI/CD
+4. Consider performance impact
+
+## Future Enhancements
+
+- Parallel test execution
+- Web dashboard for results
+- Historical trend analysis
+- Performance regression detection
+- Automated issue creation for failures
+- Integration with external monitoring tools

package/scripts/README-test-clodo-deployment.md

@@ -0,0 +1,157 @@
+# Clodo Service Deployment Testing Script
+
+A comprehensive local testing script for the clodo-service deployment process that safely simulates the information collection, consolidation, and deployment execution phases without making actual Cloudflare API calls.
+
+## Overview
+
+This script tests the complete deployment workflow by:
+1. **Information Collection**: Service detection and manifest parsing
+2. **Consolidation**: Credential gathering and configuration validation
+3. **Execution**: Simulated deployment with detailed phase-by-phase logging
+
+## Usage
+
+```bash
+# Basic test (recommended for development)
+node scripts/test-clodo-deployment.js
+
+# Test specific phase only
+node scripts/test-clodo-deployment.js --test-phase collection
+node scripts/test-clodo-deployment.js --test-phase consolidation
+node scripts/test-clodo-deployment.js --test-phase execution
+
+# Advanced options
+node scripts/test-clodo-deployment.js --verbose --service-path ./my-service
+node scripts/test-clodo-deployment.js --no-mock-credentials  # Requires real credentials
+node scripts/test-clodo-deployment.js --no-dry-run          # Actually deploy (dangerous!)
+```
+
+## Command Line Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--service-path <path>` | Path to service directory | Current directory |
+| `--dry-run` | Simulate deployment without changes | `true` (safe) |
+| `--no-dry-run` | Actually perform deployment | `false` |
+| `--verbose` | Detailed logging output | `false` |
+| `--mock-credentials` | Use mock credentials for testing | `true` (safe) |
+| `--no-mock-credentials` | Require real Cloudflare credentials | `false` |
+| `--test-phase <phase>` | Test specific phase: `all`, `collection`, `consolidation`, `execution` | `all` |
+| `--help` | Show help message | - |
+
+## Testing Phases
+
+### Phase 1: Information Collection
+- Detects if current directory is a Clodo service project
+- Parses `clodo-service-manifest.json` for service configuration
+- Validates project structure and required files
+- Extracts service name, type, domain, and environment
+
+### Phase 2: Consolidation
+- Analyzes credential gathering strategy (flags → env vars → prompt)
+- Consolidates deployment configuration from multiple sources
+- Validates all required information is present
+- Creates comprehensive deployment plan
+
+### Phase 3: Execution
+- Simulates complete deployment workflow
+- Tests each deployment phase with realistic timing
+- Validates post-deployment checks
+- Generates mock deployment results
+
+## Safety Features
+
+- **Dry Run by Default**: No actual deployments or API calls by default
+- **Mock Credentials**: Uses safe test credentials unless explicitly disabled
+- **Comprehensive Validation**: Tests all validation logic without side effects
+- **Detailed Logging**: Shows exactly what would happen in real deployment
+
+## Example Output
+
+```
+[14:23:15] 🚀 Starting Clodo Service Deployment Testing
+[14:23:15] 📋 Test Phase: all
+[14:23:15] 📋 Service Path: C:\path\to\service
+[14:23:15] 📋 Dry Run: true
+
+[14:23:15] 🚀 Phase 1: Information Collection
+[14:23:15] 📋 Step 1: Detecting service project...
+[14:23:15] ✅ Found existing service manifest
+[14:23:15] 📋 Step 2: Parsing service information...
+[14:23:15] 📋 Service Name: my-test-service
+[14:23:15] 📋 Service Type: data-service
+[14:23:15] 📋 Domain: test-service.example.com
+[14:23:15] ✅ Information collection completed in 45ms
+
+[14:23:15] 🚀 Phase 2: Information Consolidation
+[14:23:15] 📋 Step 1: Analyzing credential gathering strategy...
+[14:23:15] 📋 Using mock credentials for testing
+[14:23:15] 📋 Credential Sources:
+[14:23:15] 📋   Environment Variables: ❌
+[14:23:15] 📋   Mock Credentials: ✅
+[14:23:15] ✅ Information consolidation completed in 23ms
+
+[14:23:15] 🚀 Phase 3: Deployment Execution Simulation
+[14:23:15] 📋 Step 2: Simulating deployment phases...
+[14:23:15] 📋   Executing: Initialization...
+[14:23:15] ✅ Initialization completed
+[14:23:15] 📋   Executing: Configuration Validation...
+[14:23:15] ✅ Configuration Validation completed
+... (additional phases)
+[14:23:16] ✅ Deployment execution simulation completed in 5423ms
+
+[14:23:16] 🎉 Clodo Service Deployment Testing Complete
+```
+
+## Use Cases
+
+### Development Testing
+```bash
+# Test deployment logic during development
+node scripts/test-clodo-deployment.js --verbose
+```
+
+### CI/CD Integration
+```bash
+# Validate deployment configuration in CI
+node scripts/test-clodo-deployment.js --test-phase collection --test-phase consolidation
+```
+
+### Debugging
+```bash
+# Isolate specific deployment issues
+node scripts/test-clodo-deployment.js --test-phase execution --verbose
+```
+
+### Service Validation
+```bash
+# Validate service configuration before deployment
+node scripts/test-clodo-deployment.js --service-path ./my-service --test-phase collection
+```
+
+## Integration with Real Deployment
+
+The testing script validates the same logic as the actual deployment:
+
+1. **Manifest Parsing**: Same JSON parsing and validation as `deploy.js`
+2. **Credential Logic**: Same priority order (flags → env → prompt) as real deployment
+3. **Configuration Consolidation**: Same validation and consolidation logic
+4. **Deployment Phases**: Simulates the same phases as `ModularEnterpriseDeployer`
+
+## Troubleshooting
+
+### "No manifest found" Error
+The script will create a mock manifest for testing. For real services, ensure `clodo-service-manifest.json` exists.
+
+### Credential Issues
+Use `--mock-credentials` for testing, or provide real Cloudflare credentials via environment variables.
+
+### Permission Errors
+Ensure the script has read/write access to the service directory.
+
+## Related Files
+
+- `bin/commands/deploy.js` - Actual deployment command
+- `bin/deployment/modular-enterprise-deploy.js` - Deployment orchestrator
+- `clodo-service-manifest.json` - Service configuration file
+- `README.md` - General framework documentation