aidevops 2.52.1

package/.agent/aidevops/recommendations.md

@@ -0,0 +1,321 @@
+---
+description: Best practices and provider selection guide
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: false
+  glob: true
+  grep: true
+  webfetch: true
+---
+
+# Best Practices & Provider Selection Guide
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Hosting**: Hostinger ($, small sites), Hetzner ($$, production), Closte ($$, VPS)
+- **Deployment**: Coolify (self-hosted PaaS), Cloudron (easy app management)
+- **DNS**: Cloudflare (CDN/security), Spaceship (modern), 101domains (large portfolios), Route 53 (AWS)
+- **Security**: API tokens in `~/.config/aidevops/`, never in repo, rotate quarterly
+- **SSH**: Ed25519 keys, standardize across servers, passphrase protection
+- **Local Dev**: `.local` suffix, SSL by default, port ranges (WordPress 10000+, APIs 8000+, MCP 8080+)
+- **MCP Ports**: Sequential allocation starting from base 8081
+- **Monitoring**: Weekly status checks, monthly token rotation, quarterly audits
+<!-- AI-CONTEXT-END -->
+
+This guide outlines proven best practices for infrastructure management and helps you select the right providers for your needs, based on real-world production setups.
+
+## Available Providers
+
+### Hosting & Cloud Providers
+
+- **[Hostinger](HOSTINGER.md)** - Budget-friendly web hosting with good performance
+- **[Hetzner Cloud](HETZNER.md)** - German cloud provider with excellent price-to-performance
+- **[Closte](CLOSTE.md)** - VPS hosting with competitive pricing
+- **[Cloudron](CLOUDRON.md)** - Self-hosted app platform for easy application management
+
+### Deployment Platforms
+
+- **[Coolify](COOLIFY.md)** - Self-hosted alternative to Vercel/Netlify/Heroku
+- **[Cloudron](CLOUDRON.md)** - Self-hosted app platform with easy management
+
+### Email Services
+
+- **[Amazon SES](SES.md)** - Scalable email delivery with comprehensive monitoring
+
+### WordPress Management
+
+- **[MainWP](MAINWP.md)** - Self-hosted WordPress management platform
+
+### Security & Secrets Management
+
+- **[Vaultwarden](VAULTWARDEN.md)** - Self-hosted password and secrets management
+
+### Code Quality & Security
+
+- **[Code Auditing](CODE-AUDITING.md)** - Multi-platform code quality and security analysis
+
+### Version Control & Git Platforms
+
+- **[Git Platforms](GIT-PLATFORMS.md)** - GitHub, GitLab, Gitea, and local Git management
+
+### Domain Management & Purchasing
+
+- **[Domain Purchasing](DOMAIN-PURCHASING.md)** - Automated domain purchasing and management
+
+### DNS & Domain Providers
+
+- **[Cloudflare DNS](CLOUDFLARE-SETUP.md)** - Global CDN and DNS with comprehensive API
+- **[Spaceship](SPACESHIP.md)** - Modern domain registrar with developer-friendly API
+- **[101domains](101DOMAINS.md)** - Comprehensive registrar with extensive TLD coverage
+- **[Namecheap DNS](../configs/namecheap-dns-config.json.txt)** - Domain registrar with DNS management
+- **[Route 53](../configs/route53-dns-config.json.txt)** - AWS DNS service with advanced features
+
+### Local Development
+
+- **[LocalWP](LOCALWP-MCP.md)** - Local WordPress development with MCP integration
+- **[Localhost](LOCALHOST.md)** - Local development environment with .local domains
+- **[Context7 MCP](CONTEXT7-MCP-SETUP.md)** - Real-time documentation access for AI assistants
+- **[MCP Servers](MCP-SERVERS.md)** - Model Context Protocol server configuration
+
+### Web Crawling & Data Extraction
+
+- **[Crawl4AI](CRAWL4AI.md)** - AI-powered web crawler and scraper with LLM-friendly output
+
+## Provider Selection Guide
+
+### **For Web Hosting:**
+
+| Provider | Best For | Price Range | Key Features |
+|----------|----------|-------------|--------------|
+| **Hostinger** | Small-medium sites | $ | Easy management, good value |
+| **Hetzner Cloud** | Production apps | $$ | Excellent performance, API |
+| **Closte** | VPS hosting | $$ | Competitive pricing, flexibility |
+
+### **For Application Deployment:**
+
+| Platform | Best For | Complexity | Key Features |
+|----------|----------|------------|--------------|
+| **Coolify** | Self-hosted PaaS | Medium | Docker-based, full control |
+| **Cloudron** | App management | Low | One-click apps, easy management |
+
+### **For Email Delivery:**
+
+| Service | Best For | Complexity | Key Features |
+|---------|----------|------------|--------------|
+| **Amazon SES** | Scalable email delivery | Medium | High deliverability, comprehensive analytics |
+
+### **For DNS & Domain Management:**
+
+| Provider | Best For | API Quality | Key Features |
+|----------|----------|-------------|--------------|
+| **Cloudflare** | Global performance | Excellent | CDN, security, analytics |
+| **Spaceship** | Modern domain management | Excellent | Developer-friendly, competitive pricing |
+| **101domains** | Large portfolios | Excellent | Extensive TLDs, privacy features |
+| **Route 53** | AWS integration | Excellent | Advanced routing, health checks |
+| **Namecheap** | Domain registration | Limited | Affordable, basic DNS |
+
+## Infrastructure Organization
+
+### **Multi-Project Architecture**
+
+- **Separate API tokens** for different projects/clients
+- **Descriptive naming**: Use clear project names (main, client-project, storagebox, client-projects)
+- **Account isolation**: Keep production, development, and client projects separate
+- **Documentation**: Maintain clear descriptions for each project/account
+
+### **Hetzner Cloud Best Practices**
+
+```json
+{
+  "accounts": {
+    "main": {
+      "api_token": "YOUR_MAIN_TOKEN",
+      "description": "Main production account"
+    },
+    "client-project": {
+      "api_token": "YOUR_CLIENT_PROJECT_TOKEN",
+      "description": "Client project account"
+    },
+    "storagebox": {
+      "api_token": "YOUR_STORAGE_TOKEN",
+      "description": "Storage and backup account"
+    }
+  }
+}
+```
+
+### **Hostinger Multi-Site Management**
+
+- **Domain-based organization**: Group sites by domain/purpose
+- **Consistent paths**: Use standard `/domains/[domain]/public_html` structure
+- **Password management**: Separate password files for different server groups
+- **Site categorization**: Group by client, project type, or environment
+
+## Security Best Practices
+
+### **API Token Management**
+
+- **Secure local storage**: Store tokens in `~/.config/aidevops/` (user-private only)
+- **Never in repository**: API tokens must never be stored in repository files
+- **Environment separation**: Different tokens for prod/dev/staging
+- **Regular rotation**: Rotate tokens quarterly
+- **Least privilege**: Use minimal required permissions
+- **Git exclusion**: Always add config files to `.gitignore`
+
+### **SSH Key Standardization**
+
+- **Modern keys**: Use Ed25519 keys (faster, more secure)
+- **Key distribution**: Standardize keys across all servers
+- **Passphrase protection**: Protect private keys with passphrases
+- **Regular audits**: Audit and remove unused keys
+
+### **Password Authentication (Hostinger/Closte)**
+
+- **Secure storage**: Store passwords in separate files with 600 permissions
+- **File naming**: Use descriptive names (`hostinger_password`, `closte_web_password`)
+- **sshpass usage**: Use sshpass for automated password authentication
+- **Git exclusion**: Add password files to `.gitignore`
+
+## Domain & SSL Management
+
+### **Local Development Domains**
+
+- **Consistent naming**: Use `.local` suffix for all local development
+- **SSL by default**: Generate SSL certificates for all local domains
+- **Port standardization**: Use consistent port ranges (10000+ for WordPress)
+- **DNS resolution**: Setup dnsmasq for automatic `.local` resolution
+
+### **LocalWP Integration**
+
+- **Site naming**: Use descriptive names matching project purpose
+- **Port mapping**: Map LocalWP ports to custom `.local` domains
+- **SSL certificates**: Generate certificates for LocalWP sites
+- **Traefik integration**: Use reverse proxy for clean domain access
+
+### **Production SSL**
+
+- **Let's Encrypt**: Use automated certificate generation
+- **Wildcard certificates**: For multi-subdomain setups
+- **Certificate monitoring**: Monitor expiration dates
+- **Renewal automation**: Automate certificate renewal
+
+## 🔧 **Development Environment Setup**
+
+### **LocalWP Best Practices**
+
+```bash
+# List LocalWP sites
+./.agent/scripts/localhost-helper.sh list-localwp
+
+# Setup custom domain for LocalWP site
+./.agent/scripts/localhost-helper.sh setup-localwp-domain plugin-testing plugin-testing.local
+
+# Generate SSL certificate
+./.agent/scripts/localhost-helper.sh generate-cert plugin-testing.local
+```
+
+### **Docker Development**
+
+- **Shared networks**: Use common network for all local containers
+- **Traefik labels**: Standardize Traefik configuration
+- **Volume management**: Consistent volume naming and paths
+- **Environment variables**: Use `.env` files for configuration
+
+### **Port Management**
+
+- **WordPress sites**: 10000-10999 range
+- **API services**: 8000-8999 range
+- **MCP servers**: 8080+ range (sequential allocation)
+- **Databases**: 5432 (PostgreSQL), 3306 (MySQL), 6379 (Redis)
+
+## 🤖 **MCP Integration Best Practices**
+
+### **Port Allocation**
+
+```json
+{
+  "mcp_integration": {
+    "base_port": 8081,
+    "port_allocation": {
+      "hostinger": 8080,
+      "hetzner-main": 8081,
+      "hetzner-client-project": 8082,
+      "hetzner-storagebox": 8083,
+      "closte": 8084
+    }
+  }
+}
+```
+
+### **Service Organization**
+
+- **Sequential ports**: Allocate ports sequentially starting from base
+- **Service naming**: Use descriptive names matching account structure
+- **Secure API storage**: Use secure local storage for API tokens (never in repository)
+- **Health monitoring**: Monitor MCP server health and availability
+
+## 📁 **File Organization**
+
+### **Configuration Structure**
+
+```text
+~/
+├── hetzner-config.json           # Hetzner API tokens
+├── hostinger-config.json         # Hostinger site configurations
+├── closte-config.json            # Closte server configurations
+├── .ssh/
+│   ├── hostinger_password        # Hostinger SSH password
+│   ├── closte_password           # Closte SSH password
+│   └── config                    # SSH client configuration
+└── Local Sites/                  # LocalWP sites
+    ├── plugin-testing/
+    └── waas/
+```
+
+### **Git Repository Structure**
+
+- **Helper scripts**: Root level for easy access
+- **Configuration samples**: In `configs/` directory
+- **Documentation**: In `docs/` directory
+- **Provider scripts**: In `.agent/scripts/` directory
+
+## 🔍 **Monitoring & Maintenance**
+
+### **Regular Tasks**
+
+- **Weekly**: Check server status and resource usage
+- **Monthly**: Review and rotate API tokens
+- **Quarterly**: Audit SSH keys and access permissions
+- **Annually**: Review and update security practices
+
+### **Automation**
+
+- **Health checks**: Automated server health monitoring
+- **Backup verification**: Regular backup integrity checks
+- **Certificate monitoring**: SSL certificate expiration alerts
+- **Resource monitoring**: CPU, memory, and disk usage alerts
+
+## 🎯 **AI Assistant Integration**
+
+### **Context Documentation**
+
+- **Infrastructure inventory**: Maintain current server/site lists
+- **Access patterns**: Document common tasks and procedures
+- **Security guidelines**: Clear security boundaries and requirements
+- **Troubleshooting guides**: Common issues and solutions
+
+### **Command Standardization**
+
+- **Consistent interfaces**: Same command patterns across providers
+- **Error handling**: Comprehensive error messages and recovery suggestions
+- **Logging**: Detailed operation logs for audit and debugging
+- **Help systems**: Built-in help and usage examples
+
+---
+
+**These practices are based on real production environments and have been proven to scale effectively while maintaining security and operational efficiency.**

package/.agent/aidevops/requirements.md

@@ -0,0 +1,301 @@
+---
+description: Framework requirements and capabilities
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: false
+  glob: true
+  grep: true
+  webfetch: false
+  task: true
+---
+
+# Framework Requirements & Capabilities
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Services**: 25+ providers with unified command patterns
+- **Quality**: SonarCloud A-grade, CodeFactor A-grade, ShellCheck zero violations
+- **Security**: Zero credential exposure, encrypted storage, confirmation prompts
+- **Performance**: <1s local ops, <5s API calls, 10+ concurrent operations
+- **MCP**: Real-time data access via MCP servers
+- **Categories**: Infrastructure, Deployment, Content, Security, Quality, Git, Email, DNS, Local
+- **Quality check**: `curl -s "https://sonarcloud.io/api/measures/component?component=marcusquinn_aidevops&metricKeys=bugs,vulnerabilities,code_smells"`
+- **ShellCheck**: `find .agent/scripts/ -name "*.sh" -exec shellcheck {} \;`
+<!-- AI-CONTEXT-END -->
+
+## Core Requirements
+
+### **Functional Requirements**
+
+- **Multi-provider support**: Manage 25+ services through unified interfaces
+- **Secure credential management**: Enterprise-grade security for all credentials
+- **Consistent command patterns**: Unified command structure across all services
+- **Real-time integration**: MCP server support for live data access
+- **Intelligent setup**: Guided configuration and setup assistance
+- **Comprehensive monitoring**: Health checks and status monitoring across all services
+- **Automated operations**: Support for automated DevOps workflows
+- **Error recovery**: Robust error handling and recovery mechanisms
+
+### **Non-Functional Requirements**
+
+- **Security**: Zero credential exposure, secure by default
+- **Reliability**: 99.9% uptime for critical operations
+- **Performance**: Sub-second response times for common operations
+- **Scalability**: Support for unlimited service accounts and resources
+- **Maintainability**: Modular architecture for easy extension
+- **Usability**: Clear documentation and intuitive command patterns
+- **Compatibility**: Cross-platform support (macOS, Linux, Windows)
+- **Auditability**: Complete audit trails for all operations
+
+### **🏆 Quality Requirements (MANDATORY)**
+
+**All code changes MUST maintain these quality standards:**
+
+#### **Code Quality Platforms**
+
+- **SonarCloud**: A-grade Security, Reliability, Maintainability ratings
+- **CodeFactor**: A-grade overall rating (80%+ A-grade files)
+- **GitHub Actions**: All CI/CD checks must pass
+- **ShellCheck**: Zero violations across all shell scripts
+
+#### **Quality Metrics**
+
+- **Zero Security Vulnerabilities**: Maintain perfect security rating
+- **Zero Code Duplication**: Keep duplication at 0.0%
+- **Minimal Code Smells**: Target <400 maintainability issues
+- **Professional Standards**: Follow established shell scripting best practices
+
+#### **Quality Validation Process**
+
+1. **Pre-commit**: Run ShellCheck on all modified shell scripts
+2. **Post-commit**: Verify SonarCloud and CodeFactor improvements
+3. **Continuous**: Monitor quality platforms for regressions
+4. **Documentation**: Update quality guidelines with new learnings
+
+**Quality Check Commands:**
+
+```bash
+# SonarCloud status
+curl -s "https://sonarcloud.io/api/measures/component?component=marcusquinn_aidevops&metricKeys=bugs,vulnerabilities,code_smells"
+
+# CodeFactor status
+curl -s "https://www.codefactor.io/repository/github/marcusquinn/aidevops"
+
+# ShellCheck validation
+find .agent/scripts/ -name "*.sh" -exec shellcheck {} \;
+```
+
+## 🏗️ **Service Categories & Capabilities**
+
+### **Infrastructure & Hosting**
+
+**Services**: Hostinger, Hetzner Cloud, Closte, Cloudron
+**Capabilities**:
+
+- Server provisioning and management
+- Resource monitoring and scaling
+- Backup and disaster recovery
+- SSL certificate management
+- Load balancer configuration
+
+### **Deployment & Orchestration**
+
+**Services**: Coolify
+**Capabilities**:
+
+- Application deployment automation
+- Container orchestration
+- CI/CD pipeline management
+- Environment management
+- Rollback and recovery
+
+### **Content Management**
+
+**Services**: MainWP
+**Capabilities**:
+
+- WordPress site management at scale
+- Plugin and theme updates
+- Security scanning and monitoring
+- Backup management
+- Performance optimization
+
+### **Security & Secrets**
+
+**Services**: Vaultwarden
+**Capabilities**:
+
+- Secure credential storage and retrieval
+- Password generation and management
+- Team credential sharing
+- Audit logging and access control
+- Integration with all framework services
+
+### **Code Quality & Auditing**
+
+**Services**: CodeRabbit, CodeFactor, Codacy, SonarCloud
+**Capabilities**:
+
+- Automated code quality analysis
+- Security vulnerability detection
+- Code coverage reporting
+- Quality gate enforcement
+- Trend analysis and reporting
+
+### **Version Control & Git Platforms**
+
+**Services**: GitHub, GitLab, Gitea, Local Git
+**Capabilities**:
+
+- Repository creation and management
+- Branch and merge management
+- Issue and PR automation
+- CI/CD integration
+- Security and compliance scanning
+
+### **Email Services**
+
+**Services**: Amazon SES
+**Capabilities**:
+
+- Email delivery and monitoring
+- Bounce and complaint handling
+- Reputation management
+- Analytics and reporting
+- Template management
+
+### **Domain & DNS**
+
+**Services**: Spaceship, 101domains, Cloudflare DNS, Namecheap DNS, Route 53
+**Capabilities**:
+
+- Domain purchasing and management
+- DNS record management
+- SSL certificate provisioning
+- CDN configuration
+- Performance optimization
+
+### **Development & Local**
+
+**Services**: Localhost, LocalWP, Context7 MCP, MCP Servers
+**Capabilities**:
+
+- Local development environment setup
+- WordPress development with database access
+- Real-time documentation access
+- AI assistant data integration
+- Development workflow automation
+
+## 🔐 **Security Requirements**
+
+### **Credential Security**
+
+- **Encryption at rest**: All credentials encrypted when stored
+- **Secure transmission**: All API communications over HTTPS/TLS
+- **Access control**: Role-based access to credentials and operations
+- **Audit logging**: Complete audit trail for all credential access
+- **Regular rotation**: Automated credential rotation capabilities
+
+### **Operational Security**
+
+- **Input validation**: All inputs validated and sanitized
+- **Output sanitization**: No sensitive data in logs or output
+- **Confirmation prompts**: Required for destructive operations
+- **Rate limiting**: Respect service rate limits and implement backoff
+- **Error handling**: Secure error messages without data exposure
+
+### **Infrastructure Security**
+
+- **File permissions**: Restricted permissions on all configuration files
+- **Network security**: Secure communication channels only
+- **Process isolation**: Isolated execution environments
+- **Resource limits**: Appropriate resource limits and monitoring
+- **Vulnerability management**: Regular security updates and patches
+
+## 🚀 **Performance Requirements**
+
+### **Response Times**
+
+- **Command execution**: < 1 second for local operations
+- **API operations**: < 5 seconds for single API calls
+- **Bulk operations**: Progress reporting for long-running tasks
+- **MCP server response**: < 500ms for data retrieval
+- **Setup wizard**: < 30 seconds for complete assessment
+
+### **Throughput**
+
+- **Concurrent operations**: Support for 10+ concurrent operations
+- **Bulk processing**: Handle 100+ resources in batch operations
+- **API rate limits**: Respect and optimize within service limits
+- **Resource efficiency**: Minimal memory and CPU usage
+- **Network optimization**: Efficient API usage patterns
+
+### **Scalability**
+
+- **Service accounts**: Unlimited service accounts per provider
+- **Resource management**: Handle 1000+ resources per service
+- **Configuration size**: Support for large configuration files
+- **Log management**: Efficient log rotation and archival
+- **Cache management**: Intelligent caching for performance
+
+## 🔄 **Integration Requirements**
+
+### **MCP Server Integration**
+
+- **Real-time data access**: Live data from all integrated services
+- **Secure communication**: Encrypted MCP server communications
+- **Error handling**: Graceful degradation when MCP servers unavailable
+- **Performance optimization**: Efficient data retrieval and caching
+- **Multi-server support**: Coordinate across multiple MCP servers
+
+### **External Service Integration**
+
+- **API compatibility**: Support for REST and GraphQL APIs
+- **Authentication**: Support for various auth methods (tokens, OAuth, etc.)
+- **Webhook support**: Handle webhooks for real-time updates
+- **Batch operations**: Efficient bulk operations where supported
+- **Error recovery**: Automatic retry with exponential backoff
+
+### **AI Assistant Integration**
+
+- **Context awareness**: Provide rich context for AI decision making
+- **Command generation**: Support AI-generated command sequences
+- **Validation**: Validate AI-generated operations before execution
+- **Feedback loops**: Provide operation results back to AI systems
+- **Learning support**: Support for AI learning from operation outcomes
+
+## 📊 **Monitoring & Observability**
+
+### **Health Monitoring**
+
+- **Service health checks**: Regular health checks for all services
+- **Performance metrics**: Response time and throughput monitoring
+- **Error rate tracking**: Monitor and alert on error rates
+- **Resource utilization**: Monitor system resource usage
+- **Dependency monitoring**: Track external service dependencies
+
+### **Audit & Compliance**
+
+- **Operation logging**: Complete logs for all operations
+- **Access tracking**: Track all credential and resource access
+- **Change management**: Log all configuration and resource changes
+- **Compliance reporting**: Generate compliance reports as needed
+- **Data retention**: Appropriate data retention policies
+
+### **Alerting & Notification**
+
+- **Error alerting**: Immediate alerts for critical errors
+- **Performance degradation**: Alerts for performance issues
+- **Security events**: Immediate alerts for security incidents
+- **Maintenance windows**: Notifications for planned maintenance
+- **Status updates**: Regular status updates for long operations
+
+  task: true
+---
+
+**These requirements ensure the framework provides enterprise-grade DevOps automation capabilities while maintaining security, performance, and reliability standards.** 🎯🔒⚡