@tamyla/clodo-framework 1.0.0 → 2.0.1

package/dist/utils/ErrorHandler.js

@@ -93,6 +93,119 @@ export class ErrorHandler {
     console.error('   - Review service logs for startup errors');
   }
 
+  /**
+   * Handle D1 database related errors specifically
+   * @param {Error} error - The D1 database error
+   * @param {Object} context - Context information (environment, service, etc.)
+   */
+  static handleD1DatabaseError(error, context = {}) {
+    console.error(`\n❌ D1 Database Error`);
+    console.error(`   Environment: ${context.environment || 'unknown'}`);
+    console.error(`   Service: ${context.service || 'unknown'}`);
+    console.error(`   Error: ${error.message}`);
+    const errorMessage = error.message.toLowerCase();
+    if (errorMessage.includes("couldn't find a d1 db")) {
+      console.error('\n🗄️ D1 Database Not Found:');
+      console.error('   - The database specified in wrangler.toml does not exist');
+      console.error('   - Check database name and ID in [[d1_databases]] section');
+      console.error('   - List available databases: wrangler d1 list');
+      console.error('   - Create missing database: wrangler d1 create <database-name>');
+      console.error('   - Verify you\'re authenticated to the correct Cloudflare account');
+    } else if (errorMessage.includes('binding') && errorMessage.includes('not found')) {
+      console.error('\n🔗 D1 Binding Configuration Error:');
+      console.error('   - Check [[d1_databases]] section in wrangler.toml');
+      console.error('   - Ensure binding name matches what your code expects');
+      console.error('   - Verify database_name and database_id are correct');
+      console.error('   - Example configuration:');
+      console.error('     [[d1_databases]]');
+      console.error('     binding = "DB"');
+      console.error('     database_name = "my-database"');
+      console.error('     database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"');
+    } else if (errorMessage.includes('unauthorized') || errorMessage.includes('forbidden')) {
+      console.error('\n🔒 D1 Permission Error:');
+      console.error('   - Verify Cloudflare API token has D1 permissions');
+      console.error('   - Check if you have access to the specified database');
+      console.error('   - Ensure you\'re authenticated to the correct account');
+      console.error('   - Re-authenticate: wrangler auth login');
+    } else if (errorMessage.includes('migration')) {
+      console.error('\n🔄 D1 Migration Error:');
+      console.error('   - Check migration files for syntax errors');
+      console.error('   - Verify migration file names follow correct format');
+      console.error('   - List migrations: wrangler d1 migrations list <database>');
+      console.error('   - Apply migrations manually: wrangler d1 migrations apply <database>');
+    } else {
+      console.error('\n💡 General D1 Troubleshooting:');
+      console.error('   - Check Cloudflare account has D1 enabled');
+      console.error('   - Verify wrangler is up to date: npm install -g wrangler');
+      console.error('   - List available databases: wrangler d1 list');
+      console.error('   - Check database status in Cloudflare Dashboard');
+      console.error('   - Review wrangler.toml configuration file');
+    }
+    console.error('\n📚 Additional Resources:');
+    console.error('   - D1 Documentation: https://developers.cloudflare.com/d1/');
+    console.error('   - Wrangler D1 Commands: wrangler d1 --help');
+    console.error('   - Framework D1 Integration Guide: docs/guides/d1-setup.md');
+  }
+
+  /**
+   * Analyze error and provide specific D1 recovery suggestions
+   * @param {Error} error - The error to analyze
+   * @returns {Object} Analysis result with suggestions
+   */
+  static analyzeD1Error(error) {
+    const errorMessage = error.message.toLowerCase();
+    const analysis = {
+      isD1Error: false,
+      category: 'unknown',
+      severity: 'medium',
+      autoFixable: false,
+      suggestions: []
+    };
+
+    // Check if this is a D1 related error
+    if (errorMessage.includes('d1') || errorMessage.includes('database') || errorMessage.includes('binding')) {
+      analysis.isD1Error = true;
+    }
+    if (errorMessage.includes("couldn't find a d1 db")) {
+      analysis.category = 'database_not_found';
+      analysis.severity = 'high';
+      analysis.autoFixable = true;
+      analysis.suggestions = ['Run automated D1 recovery: Check available databases and create/configure as needed', 'Manual fix: wrangler d1 list && wrangler d1 create <name>', 'Update wrangler.toml with correct database_id'];
+    } else if (errorMessage.includes('binding') && errorMessage.includes('not found')) {
+      analysis.category = 'binding_configuration';
+      analysis.severity = 'medium';
+      analysis.autoFixable = true;
+      analysis.suggestions = ['Run configuration validator to check [[d1_databases]] section', 'Verify binding name matches code expectations', 'Update database_name and database_id in wrangler.toml'];
+    } else if (errorMessage.includes('unauthorized') || errorMessage.includes('forbidden')) {
+      analysis.category = 'authentication';
+      analysis.severity = 'high';
+      analysis.autoFixable = false;
+      analysis.suggestions = ['Re-authenticate with Cloudflare: wrangler auth login', 'Check API token permissions include D1 access', 'Verify correct Cloudflare account is selected'];
+    } else if (errorMessage.includes('migration')) {
+      analysis.category = 'migration';
+      analysis.severity = 'medium';
+      analysis.autoFixable = false;
+      analysis.suggestions = ['Check migration files for syntax errors', 'Apply migrations manually: wrangler d1 migrations apply', 'Reset migrations if needed: wrangler d1 migrations list'];
+    }
+    return analysis;
+  }
+
+  /**
+   * Get step-by-step D1 troubleshooting guide
+   * @param {string} errorType - Type of D1 error
+   * @returns {Array<string>} Step-by-step guide
+   */
+  static getD1TroubleshootingSteps(errorType) {
+    const guides = {
+      database_not_found: ['1. List available databases: wrangler d1 list', '2. Check if database name in wrangler.toml matches an existing database', '3. If database doesn\'t exist, create it: wrangler d1 create <database-name>', '4. Copy the database ID from the creation output', '5. Update database_id in wrangler.toml [[d1_databases]] section', '6. Retry deployment: npm run deploy'],
+      binding_configuration: ['1. Open wrangler.toml and locate [[d1_databases]] section', '2. Verify binding name matches what your code expects (usually "DB")', '3. Check database_name is correct (no typos)', '4. Verify database_id is a valid UUID format', '5. Test configuration: wrangler deploy --dry-run', '6. If issues persist, validate with: wrangler d1 info <database-name>'],
+      authentication: ['1. Log out of current session: wrangler logout', '2. Re-authenticate: wrangler auth login', '3. Verify correct account: wrangler whoami', '4. Check API token permissions if using token authentication', '5. Ensure token has D1:Edit permissions in Cloudflare dashboard', '6. Retry the operation after successful authentication'],
+      migration: ['1. Check migration files in migrations/ directory', '2. Validate SQL syntax in migration files', '3. List current migration status: wrangler d1 migrations list <database>', '4. Apply pending migrations: wrangler d1 migrations apply <database>', '5. If errors occur, check migration file format and naming', '6. Consider rolling back problematic migrations if needed'],
+      general: ['1. Check Cloudflare account has D1 enabled and available', '2. Update wrangler to latest version: npm install -g wrangler', '3. Verify wrangler.toml file exists and has correct format', '4. Test authentication: wrangler whoami', '5. List available D1 databases: wrangler d1 list', '6. Check Cloudflare Dashboard for any service issues']
+    };
+    return guides[errorType] || guides.general;
+  }
+
   /**
    * Handle configuration errors
    * @param {Error} error - The configuration error

package/dist/utils/scripts-manager.js

@@ -0,0 +1,167 @@
+/**
+ * Scripts Manager
+ *
+ * Manages and executes development scripts from the scripts/ directory
+ * Provides interactive access to generated deployment and utility scripts
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
+class ScriptsManager {
+  constructor() {
+    this.scriptsDir = path.join(process.cwd(), 'scripts');
+    this.scripts = new Map();
+  }
+
+  /**
+   * Load available scripts from scripts/ directory
+   */
+  async loadScripts() {
+    if (!fs.existsSync(this.scriptsDir)) {
+      return;
+    }
+    const subdirs = ['database', 'deployment', 'service-management', 'testing', 'utilities'];
+    for (const subdir of subdirs) {
+      const subdirPath = path.join(this.scriptsDir, subdir);
+      if (fs.existsSync(subdirPath)) {
+        await this.loadScriptsFromDir(subdirPath, subdir);
+      }
+    }
+  }
+
+  /**
+   * Load scripts from a specific directory
+   */
+  async loadScriptsFromDir(dirPath, category) {
+    const files = fs.readdirSync(dirPath).filter(f => f.endsWith('.js') || f.endsWith('.ps1') || f.endsWith('.sh'));
+    for (const file of files) {
+      const filePath = path.join(dirPath, file);
+      const scriptName = path.basename(file, path.extname(file));
+      const scriptKey = `${category}/${scriptName}`;
+      this.scripts.set(scriptKey, {
+        name: scriptName,
+        path: filePath,
+        category,
+        extension: path.extname(file),
+        description: await this.getScriptDescription(filePath)
+      });
+    }
+  }
+
+  /**
+   * Get script description from file content or comments
+   */
+  async getScriptDescription(filePath) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const lines = content.split('\n').slice(0, 10);
+      for (const line of lines) {
+        const commentMatch = line.match(/^\s*\/\*\*\s*@description\s+(.+)\s*\*\//) || line.match(/^\s*#\s*@description\s+(.+)/) || line.match(/^\s*\/\/\s*@description\s+(.+)/);
+        if (commentMatch) {
+          return commentMatch[1].trim();
+        }
+      }
+
+      // Fallback: first comment line
+      for (const line of lines) {
+        const commentMatch = line.match(/^\s*\/\*\*\s*(.+)\s*\*\//) || line.match(/^\s*#\s*(.+)/) || line.match(/^\s*\/\/\s*(.+)/);
+        if (commentMatch && !commentMatch[1].includes('@')) {
+          return commentMatch[1].trim();
+        }
+      }
+    } catch (error) {
+      // Ignore errors
+    }
+    return 'No description available';
+  }
+
+  /**
+   * Get all available scripts
+   */
+  getAllScripts() {
+    return Array.from(this.scripts.values());
+  }
+
+  /**
+   * Get scripts by category
+   */
+  getScriptsByCategory(category) {
+    return Array.from(this.scripts.values()).filter(script => script.category === category);
+  }
+
+  /**
+   * Execute a script
+   */
+  async executeScript(scriptKey, args = []) {
+    const script = this.scripts.get(scriptKey);
+    if (!script) {
+      throw new Error(`Script not found: ${scriptKey}`);
+    }
+    const command = this.buildCommand(script, args);
+    try {
+      const {
+        stdout,
+        stderr
+      } = await execAsync(command);
+      return {
+        stdout,
+        stderr,
+        success: true
+      };
+    } catch (error) {
+      return {
+        stdout: error.stdout,
+        stderr: error.stderr,
+        success: false,
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * Build execution command based on script type
+   */
+  buildCommand(script, args) {
+    const argsStr = args.join(' ');
+    switch (script.extension) {
+      case '.js':
+        return `node "${script.path}" ${argsStr}`;
+      case '.ps1':
+        return `powershell -ExecutionPolicy Bypass -File "${script.path}" ${argsStr}`;
+      case '.sh':
+        return `bash "${script.path}" ${argsStr}`;
+      default:
+        throw new Error(`Unsupported script type: ${script.extension}`);
+    }
+  }
+
+  /**
+   * List available scripts in a formatted way
+   */
+  listScripts() {
+    const scripts = this.getAllScripts();
+    const categories = {};
+    scripts.forEach(script => {
+      if (!categories[script.category]) {
+        categories[script.category] = [];
+      }
+      categories[script.category].push(script);
+    });
+    let output = 'Available Scripts:\n\n';
+    for (const [category, scripts] of Object.entries(categories)) {
+      output += `${category.toUpperCase()}:\n`;
+      scripts.forEach(script => {
+        output += `  ${script.name}: ${script.description}\n`;
+      });
+      output += '\n';
+    }
+    return output;
+  }
+}
+
+// Export singleton instance
+export const scriptsManager = new ScriptsManager();
+export default scriptsManager;

package/dist/utils/ui-structures-loader.js

@@ -0,0 +1,110 @@
+/**
+ * UI Structures Loader
+ *
+ * Loads and provides access to UI templates from ui-structures directory
+ * These templates define the interactive data collection workflows
+ */
+
+import fs from 'fs';
+import path from 'path';
+class UIStructuresLoader {
+  constructor() {
+    this.templates = new Map();
+    this.loaded = false;
+  }
+
+  /**
+   * Load all UI structure templates
+   */
+  async loadTemplates() {
+    if (this.loaded) return;
+    const uiStructuresDir = path.join(process.cwd(), 'ui-structures');
+
+    // Load creation templates
+    const creationDir = path.join(uiStructuresDir, 'creation');
+    if (fs.existsSync(creationDir)) {
+      const creationFiles = fs.readdirSync(creationDir).filter(f => f.endsWith('.json'));
+      for (const file of creationFiles) {
+        const filePath = path.join(creationDir, file);
+        const content = fs.readFileSync(filePath, 'utf8');
+        const template = JSON.parse(content);
+        this.templates.set(template.template.name, template);
+      }
+    }
+
+    // Load reference templates
+    const referenceDir = path.join(uiStructuresDir, 'reference');
+    if (fs.existsSync(referenceDir)) {
+      const referenceFiles = fs.readdirSync(referenceDir).filter(f => f.endsWith('.json'));
+      for (const file of referenceFiles) {
+        const filePath = path.join(referenceDir, file);
+        const content = fs.readFileSync(filePath, 'utf8');
+        const template = JSON.parse(content);
+        // Use template.name if available, otherwise filename
+        const name = template.template?.name || path.basename(file, '.json');
+        this.templates.set(name, template);
+      }
+    }
+    this.loaded = true;
+  }
+
+  /**
+   * Get a specific template by name
+   */
+  getTemplate(name) {
+    return this.templates.get(name);
+  }
+
+  /**
+   * Get all templates
+   */
+  getAllTemplates() {
+    return Array.from(this.templates.values());
+  }
+
+  /**
+   * Get templates by category
+   */
+  getTemplatesByCategory(category) {
+    return Array.from(this.templates.values()).filter(template => template.template?.category === category);
+  }
+
+  /**
+   * Get core inputs UI template
+   */
+  getCoreInputsTemplate() {
+    return this.getTemplate('core-inputs-ui');
+  }
+
+  /**
+   * Get smart confirmable UI template
+   */
+  getSmartConfirmableTemplate() {
+    return this.getTemplate('smart-confirmable-ui');
+  }
+
+  /**
+   * Get automated generation UI template
+   */
+  getAutomatedGenerationTemplate() {
+    return this.getTemplate('automated-generation-ui');
+  }
+
+  /**
+   * Get service manifest template
+   */
+  getServiceManifestTemplate() {
+    return this.getTemplate('service-manifest');
+  }
+
+  /**
+   * Get absolutely required inputs reference
+   */
+  getAbsolutelyRequiredInputs() {
+    return this.getTemplate('absolutely-required-inputs');
+  }
+}
+
+// Export singleton instance
+export const uiStructuresLoader = new UIStructuresLoader();
+export default uiStructuresLoader;

package/docs/README.md

@@ -1,82 +1,35 @@
-# Clodo Framework Documentation
+# CLODO Framework Documentation
 
 > A comprehensive framework for building Clodo-style microservices on Cloudflare Workers + D1
 
-## 📚 Documentation Structure
+## 📚 Essential Documentation
 
-### **Getting Started**
-- **[Overview](./overview.md)** - Framework philosophy and core concepts
-- **[Developer Guide](./guides/developer-guide.md)** - Comprehensive guide for external developers
-- **[Quick Start Guide](./guides/getting-started.md)** - Build your first service in 5 minutes
-- **[Installation](./guides/installation.md)** - Setup and prerequisites
-
-### **Architecture**
-- **[Framework Architecture Overview](./FRAMEWORK-ARCHITECTURE-OVERVIEW.md)** - User-friendly architecture guide
-- **[Framework Architecture Analysis](./FRAMEWORK-ARCHITECTURE-ANALYSIS.md)** - Detailed technical analysis (internal)
-- **[Core Components](./architecture/components.md)** - Deep dive into framework modules
-- **[Configuration System](./architecture/configuration.md)** - Domain and feature management
-- **[Data Layer](./architecture/data-layer.md)** - Services, schemas, and database integration
-- **[Worker Integration](./architecture/worker-integration.md)** - Cloudflare Workers patterns
-
-### **Guides**
-- **[Creating Services](./guides/creating-services.md)** - Service generation and templates
-- **[Domain Configuration](./guides/domain-configuration.md)** - Multi-tenant setup
-- **[Feature Management](./guides/feature-flags.md)** - Feature flags and runtime control
-- **[Authentication](./guides/authentication.md)** - Security patterns and implementation
-- **[Database Operations](./guides/database-operations.md)** - CRUD patterns and data modeling
-
-### **Deployment**
-- **[Environment Setup](./deployment/environment-setup.md)** - Cloudflare and local development
-- **[Deployment Guide](./deployment/deployment-guide.md)** - Production deployment strategies
-- **[CI/CD Integration](./deployment/ci-cd.md)** - Automated deployment pipelines
-- **[Monitoring](./deployment/monitoring.md)** - Observability and debugging
-
-### **API Reference**
-- **[Core Classes](./api/core-classes.md)** - Framework class references
-- **[Configuration API](./api/configuration.md)** - Domain and feature APIs
-- **[Service API](./api/services.md)** - Data service interfaces
-- **[Worker Helpers](./api/worker-helpers.md)** - Cloudflare Worker utilities
-- **[CLI Tools](./api/cli-tools.md)** - Command-line interface documentation
+This folder contains **only essential, public-facing documentation** that is distributed with the npm package. For comprehensive documentation, examples, and guides, visit the [GitHub repository](https://github.com/tamylaa/clodo-framework).
 
-### **Examples**
-- **[Basic CRUD Service](./examples/basic-crud.md)** - Simple data service example
-- **[Multi-Tenant SaaS](./examples/multi-tenant-saas.md)** - Complex multi-domain setup
-- **[Authentication Service](./examples/auth-service.md)** - JWT-based authentication
-- **[API Gateway](./examples/api-gateway.md)** - Service orchestration patterns
+### **Core Documentation**
+- **[Overview](./overview.md)** - Framework philosophy and core concepts
+- **[Security](./SECURITY.md)** - Security considerations and best practices
+- **[API Reference](./api-reference.md)** - Complete API documentation
 
-### **Decision Framework**
-- **[When to Use](./decision-framework.md)** - Use cases and anti-patterns
-- **[Alternatives](./alternatives.md)** - Other approaches and trade-offs
-- **[Migration Guide](./migration-guide.md)** - Moving to/from the framework
+### **Package Contents**
+This documentation is included in the npm package distribution to provide essential information for developers using the framework.
 
-## 🚀 Quick Navigation
+## 🆘 Getting Help
 
-| I want to... | Go to |
-|--------------|--------|
-| **Understand the framework** | [Overview](./overview.md) |
-| **Learn comprehensive usage** | [Developer Guide](./guides/developer-guide.md) |
-| **Build my first service** | [Getting Started](./guides/getting-started.md) |
-| **Configure domains** | [Domain Configuration](./guides/domain-configuration.md) |
-| **Deploy to production** | [Deployment Guide](./deployment/deployment-guide.md) |
-| **Find API documentation** | [API Reference](./api/README.md) |
-| **See real examples** | [Examples](./examples/README.md) |
-| **Decide if this is right for me** | [Decision Framework](./decision-framework.md) |
+- **Framework Issues**: [GitHub Issues](https://github.com/tamylaa/clodo-framework/issues)
+- **Security Concerns**: Review [Security Documentation](./SECURITY.md)
+- **API Questions**: See [API Reference](./api-reference.md)
 
-## 🆘 Getting Help
+## 📦 Package Information
 
-- **Documentation Issues**: Open an issue in the repository
-- **Framework Bugs**: Report via GitHub Issues
-- **Questions**: Check existing issues or create a new discussion
-- **Contributing**: See [Contributing Guide](../CONTRIBUTING.md)
+- **Version**: 1.0.0
+- **License**: See repository LICENSE file
+- **Repository**: [GitHub](https://github.com/tamylaa/clodo-framework)
 
-## 🔗 External Resources
+---
 
-- **[Cloudflare Workers Documentation](https://developers.cloudflare.com/workers/)**
-- **[D1 Database Documentation](https://developers.cloudflare.com/d1/)**
-- **[Wrangler CLI Documentation](https://developers.cloudflare.com/workers/wrangler/)**
+**For comprehensive documentation, visit the [GitHub repository](https://github.com/tamylaa/clodo-framework).**
 
 ---
 
-**Framework Version**: 1.0.0  
-**Last Updated**: September 27, 2025  
-**Cloudflare Workers Runtime**: Compatible with 2023-05-18 and later
+**For comprehensive documentation, visit the [GitHub repository](https://github.com/tamylaa/clodo-framework).**