aidevops 2.52.1 → 2.53.1

package/.agent/aidevops/troubleshooting.md

@@ -1,389 +0,0 @@
----
-description: Troubleshooting guide for common issues
-mode: subagent
-tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
----
-
-# Troubleshooting Guide
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-**Before reporting a bug**: Check service status page first.
-
-**Service Status Pages**:
-- GitHub: https://www.githubstatus.com/
-- GitLab: https://status.gitlab.com/
-- Cloudflare: https://www.cloudflarestatus.com/
-- Hetzner: https://status.hetzner.com/
-- Hostinger: https://status.hostinger.com/
-- SonarCloud: https://sonarcloudstatus.io/
-- Codacy: https://status.codacy.com/
-- Snyk: https://status.snyk.io/
-
-**MCP Issues**:
-- Chrome DevTools: Install Chrome Canary, fix permissions
-- Playwright: Install browsers (`bunx playwright install`)
-- API Auth: Verify keys with curl, check env vars
-- Debug: `DEBUG=chrome-devtools-mcp bunx chrome-devtools-mcp@latest`
-- Diagnostics: `bash .agent/scripts/collect-mcp-diagnostics.sh`
-
-**Retry Strategy**: Use exponential backoff for transient failures
-<!-- AI-CONTEXT-END -->
-
-## Common Issues & Solutions
-
-### **Chrome DevTools MCP Issues**
-
-#### **Issue: Chrome not launching**
-
-```bash
-# Solution: Install Chrome Canary
-brew install --cask google-chrome-canary
-
-# Or use stable Chrome
-npx chrome-devtools-mcp@latest --channel=stable
-```
-
-#### **Issue: Permission denied errors**
-
-```bash
-# Solution: Fix permissions
-sudo chown -R $(whoami) ~/.cache/puppeteer
-chmod +x ~/.cache/puppeteer/*/chrome-*/chrome
-```
-
-#### **Issue: Headless mode not working**
-
-```bash
-# Solution: Enable headless mode explicitly
-npx chrome-devtools-mcp@latest --headless=true --no-sandbox
-```
-
-### **Playwright MCP Issues**
-
-#### **Issue: Browsers not installed**
-
-```bash
-# Solution: Install all browsers
-npx playwright install
-
-# Install specific browser
-npx playwright install chromium
-```
-
-#### **Issue: Browser launch timeout**
-
-```bash
-# Solution: Increase timeout and disable sandbox
-npx playwright-mcp@latest --timeout=60000 --no-sandbox
-```
-
-#### **Issue: WebKit not working on Linux**
-
-```bash
-# Solution: Install WebKit dependencies
-sudo apt-get install libwoff1 libopus0 libwebp6 libwebpdemux2 libenchant1c2a libgudev-1.0-0 libsecret-1-0 libhyphen0 libgdk-pixbuf2.0-0 libegl1 libnotify4 libxss1 libasound2
-```
-
-### **API-Based MCP Issues**
-
-#### **Issue: Ahrefs MCP "connection closed" error**
-
-This is a common issue with multiple potential causes:
-
-**Cause 1: Wrong API key type**
-
-```bash
-# JWT-style tokens (long, with dots) do NOT work
-# Use standard 40-character API key from https://ahrefs.com/api
-
-# Verify your key format - should be ~40 alphanumeric characters
-echo $AHREFS_API_KEY | wc -c  # Should be around 40-45
-```
-
-**Cause 2: Wrong environment variable name**
-
-```bash
-# The @ahrefs/mcp package expects API_KEY, not AHREFS_API_KEY
-# Store as AHREFS_API_KEY in your env, but pass as API_KEY to the MCP
-```
-
-**Cause 3: OpenCode environment blocks don't expand variables**
-
-```bash
-# This does NOT work in OpenCode - treats ${AHREFS_API_KEY} as literal string:
-# "env": { "API_KEY": "${AHREFS_API_KEY}" }
-
-# Solution: Use bash wrapper pattern to expand at runtime:
-# "command": ["/bin/bash", "-c", "API_KEY=$AHREFS_API_KEY npx -y @ahrefs/mcp@latest"]
-```
-
-**Working OpenCode configuration:**
-
-```json
-{
-  "ahrefs": {
-    "type": "local",
-    "command": [
-      "/bin/bash",
-      "-c",
-      "API_KEY=$AHREFS_API_KEY /opt/homebrew/bin/npx -y @ahrefs/mcp@latest"
-    ],
-    "enabled": true
-  }
-}
-```
-
-**Verify API key works:**
-
-```bash
-# Test the API directly
-curl -H "Authorization: Bearer $AHREFS_API_KEY" https://apiv2.ahrefs.com/v2/subscription_info
-
-# Should return JSON with subscription info, not an error
-```
-
-#### **Issue: Ahrefs API authentication failed**
-
-```bash
-# Solution: Verify API key
-export AHREFS_API_KEY="your_actual_api_key"
-curl -H "Authorization: Bearer $AHREFS_API_KEY" https://apiv2.ahrefs.com/v2/subscription_info
-```
-
-#### **Issue: Perplexity API rate limiting**
-
-```bash
-# Solution: Implement rate limiting
-export PERPLEXITY_RATE_LIMIT="10" # requests per minute
-```
-
-#### **Issue: Cloudflare API errors**
-
-```bash
-# Solution: Verify credentials
-export CLOUDFLARE_ACCOUNT_ID="your_account_id"
-export CLOUDFLARE_API_TOKEN="your_api_token"
-curl -X GET "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID" \
-  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
-```
-
-## Debugging Steps
-
-### **1. Check MCP Server Status**
-
-```bash
-# Test if MCP server is responding
-npx chrome-devtools-mcp@latest --test-connection
-
-# Check server logs
-tail -f /tmp/chrome-mcp.log
-```
-
-### **2. Validate Configuration**
-
-```bash
-# Validate JSON configuration
-python -m json.tool configs/mcp-templates/complete-mcp-config.json
-
-# Test individual MCP
-npx chrome-devtools-mcp@latest --config-test
-```
-
-### **3. Network Connectivity**
-
-```bash
-# Test network access
-curl -I https://api.ahrefs.com
-curl -I https://api.perplexity.ai
-curl -I https://api.cloudflare.com
-```
-
-### **4. Environment Variables**
-
-```bash
-# Check environment variables
-echo $AHREFS_API_KEY
-echo $PERPLEXITY_API_KEY
-echo $CLOUDFLARE_ACCOUNT_ID
-echo $CLOUDFLARE_API_TOKEN
-```
-
-### **5. Test Configuration Changes with CLI**
-
-The OpenCode TUI requires restart to pick up `opencode.json` changes. Use CLI for quick testing:
-
-```bash
-# Test new MCP configuration
-opencode run "List available tools from dataforseo_*" --agent SEO
-
-# Debug MCP connection (shows errors in terminal)
-opencode run "Call serper_google_search with query 'test'" --agent SEO 2>&1
-
-# Verify agent has correct tool access
-opencode run "What MCP tools can you access?" --agent SEO
-
-# Test slash commands
-opencode run "/new-command arg1" --agent Build+
-```
-
-**Workflow for adding new MCPs:**
-
-1. Edit `~/.config/opencode/opencode.json`
-2. Test with CLI: `opencode run "Test [mcp]" --agent [agent] 2>&1`
-3. If working, restart TUI to use interactively
-4. If failing, check stderr output and iterate on config
-5. Update `generate-opencode-agents.sh` to persist changes
-
-**Helper script for common tests:**
-
-```bash
-~/.aidevops/agents/scripts/opencode-test-helper.sh test-mcp dataforseo SEO
-~/.aidevops/agents/scripts/opencode-test-helper.sh test-agent Plan+
-```
-
-## Performance Optimization
-
-### **Chrome DevTools Optimization**
-
-```json
-{
-  "chrome-devtools": {
-    "args": [
-      "--disable-dev-shm-usage",
-      "--disable-gpu",
-      "--disable-background-timer-throttling",
-      "--disable-backgrounding-occluded-windows",
-      "--disable-renderer-backgrounding"
-    ]
-  }
-}
-```
-
-### **Playwright Optimization**
-
-```json
-{
-  "playwright": {
-    "args": [
-      "--disable-dev-shm-usage",
-      "--disable-gpu",
-      "--no-first-run",
-      "--no-default-browser-check"
-    ]
-  }
-}
-```
-
-## Monitoring & Logging
-
-### **Enable Debug Logging**
-
-```bash
-# Chrome DevTools debug
-DEBUG=chrome-devtools-mcp npx chrome-devtools-mcp@latest
-
-# Playwright debug
-DEBUG=pw:api npx playwright-mcp@latest
-```
-
-### **Log File Locations**
-
-```text
-Chrome DevTools: /tmp/chrome-mcp.log
-Playwright: /tmp/playwright-mcp.log
-API MCPs: ~/.mcp/logs/
-```
-
-### **Health Check Script**
-
-```bash
-#!/bin/bash
-# MCP Health Check
-echo "🔍 Checking MCP integrations..."
-
-# Test Chrome DevTools
-if npx chrome-devtools-mcp@latest --health-check; then
-  echo "✅ Chrome DevTools MCP: OK"
-else
-  echo "❌ Chrome DevTools MCP: FAILED"
-fi
-
-# Test Playwright
-if npx playwright-mcp@latest --health-check; then
-  echo "✅ Playwright MCP: OK"
-else
-  echo "❌ Playwright MCP: FAILED"
-fi
-
-# Test API connections
-if curl -s https://api.ahrefs.com > /dev/null; then
-  echo "✅ Ahrefs API: Reachable"
-else
-  echo "❌ Ahrefs API: Unreachable"
-fi
-```
-
-## Recovery Procedures
-
-### **Reset MCP Configuration**
-
-```bash
-# Backup current config
-cp ~/.config/mcp/config.json ~/.config/mcp/config.json.backup
-
-# Reset to defaults
-rm ~/.config/mcp/config.json
-bash .agent/scripts/setup-mcp-integrations.sh all
-```
-
-### **Clear Cache and Restart**
-
-```bash
-# Clear browser cache
-rm -rf ~/.cache/puppeteer
-rm -rf ~/.cache/playwright
-
-# Reinstall browsers
-npx playwright install --force
-```
-
-### **Emergency Fallback**
-
-```bash
-# Use basic configuration without advanced features
-npx chrome-devtools-mcp@latest --safe-mode
-npx playwright-mcp@latest --basic-mode
-```
-
-## Getting Help
-
-### **Log Collection for Support**
-
-```bash
-# Collect diagnostic information
-bash .agent/scripts/collect-mcp-diagnostics.sh
-
-# This creates: mcp-diagnostics-$(date +%Y%m%d).tar.gz
-```
-
-### **Community Resources**
-
-- [MCP GitHub Discussions](https://github.com/modelcontextprotocol/discussions)
-- [Chrome DevTools MCP Issues](https://github.com/chromedevtools/chrome-devtools-mcp/issues)
-- [Playwright Community](https://playwright.dev/community)
-
-### **Professional Support**
-
-- Ahrefs API Support: [support@ahrefs.com](mailto:support@ahrefs.com)
-- Cloudflare Support: [Cloudflare Support Portal](https://support.cloudflare.com/)
-- Perplexity API: [Perplexity Documentation](https://docs.perplexity.ai/)

package/.agent/aidevops.md

@@ -1,124 +0,0 @@
----
-name: aidevops
-description: AI DevOps framework operations - setup, configuration, meta-agents, troubleshooting
-mode: subagent
----
-
-# AI DevOps - Framework Main Agent
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **Purpose**: Manage and extend the aidevops framework
-- **Repo**: `~/Git/aidevops/`
-- **User Install**: `~/.aidevops/agents/`
-- **Scripts**: `.agent/scripts/[service]-helper.sh [command] [account] [target]`
-
-**Key Operations**:
-- Setup: `./setup.sh`
-- Quality check: `.agent/scripts/linters-local.sh`
-- Release: `.agent/scripts/version-manager.sh release [major|minor|patch]`
-
-**Subagents** (`aidevops/`):
-- `setup.md` - AI guide to setup.sh
-- `troubleshooting.md` - Service status, debugging
-- `architecture.md` - Framework structure
-
-**Related Subagents** (in `tools/`):
-- `tools/build-agent/` - Agent design and composition
-- `tools/build-mcp/` - MCP server development
-
-**Services**: Hostinger, Hetzner, Cloudflare, GitHub/GitLab/Gitea, MainWP,
-Vaultwarden, SonarCloud, Codacy, CodeRabbit, Snyk, Crawl4AI, MCP integrations
-
-**Testing**: Use OpenCode CLI to test config changes without restarting TUI:
-
-```bash
-opencode run "Test query" --agent AI-DevOps
-```text
-
-See `tools/opencode/opencode.md` for CLI testing patterns.
-
-<!-- AI-CONTEXT-END -->
-
-## Framework Overview
-
-AI DevOps provides comprehensive infrastructure management for AI agents:
-
-- **Infrastructure**: Hostinger, Hetzner, Closte, Cloudron
-- **Deployment**: Coolify, Vercel
-- **Content**: WordPress (MainWP, LocalWP)
-- **Quality**: SonarCloud, Codacy, CodeRabbit, Snyk, Secretlint
-- **Git**: GitHub, GitLab, Gitea with CLI integrations
-- **DNS/Domains**: Cloudflare, Spaceship, 101domains, Route53
-- **Security**: Vaultwarden, credential management
-- **Email**: Amazon SES
-
-## Command Pattern
-
-All services follow unified patterns:
-
-```bash
-.agent/scripts/[service]-helper.sh [command] [account] [target] [options]
-
-# Common commands
-help                    # Show service-specific help
-accounts|instances      # List configured accounts
-monitor|audit|status    # Service monitoring
-```text
-
-## Configuration
-
-```bash
-# Templates (committed)
-configs/[service]-config.json.txt
-
-# Working configs (gitignored)
-configs/[service]-config.json
-
-# Credentials
-~/.config/aidevops/mcp-env.sh
-```text
-
-## Quality Standards
-
-- SonarCloud: A-grade (zero vulnerabilities, bugs)
-- ShellCheck: Zero violations
-- Pattern: `local var="$1"` not `$1` directly
-- Explicit `return 0/1` in all functions
-
-## Extending the Framework
-
-See `aidevops/extension.md` for adding new services:
-
-1. Create helper script following existing patterns
-2. Add config template
-3. Create agent documentation
-4. Update service index
-5. Test thoroughly
-
-## MCP Integrations
-
-```text
-Port 3001: LocalWP WordPress database
-Port 3002: Vaultwarden credentials
-+ Chrome DevTools, Playwright, Ahrefs, Context7, GSC MCPs
-```text
-
-## OpenCode Plugins
-
-**Antigravity OAuth** (`opencode-antigravity-auth`): Enables Google OAuth for OpenCode,
-providing access to Antigravity rate limits and premium models.
-
-```bash
-# Authenticate after setup
-opencode auth login
-# Select: Google → OAuth with Google (Antigravity)
-```text
-
-**Available models**: gemini-3-pro-high, claude-opus-4-5-thinking, claude-sonnet-4-5-thinking
-
-**Multi-account**: Add multiple Google accounts for load balancing and failover.
-
-See: https://github.com/NoeFabris/opencode-antigravity-auth