Add comprehensive development guidelines document

Created DEVELOPMENT-GUIDELINES.md as reference for maintaining consistency: Structure: - Complete project file map with quick reference table - Standard script template with proper path resolution - User experience guidelines (cancel options, messaging) - Shared resources documentation (reference DB, IP reputation, user manager) - Testing checklist and guidelines - Git workflow and commit message template - Menu structure standards - Quick reference for common tasks Key Standards Documented: - Mandatory cancel/back options on all inputs - Consistent messaging (print_success, print_error, etc.) - Proper path resolution for nested scripts - Reference database usage patterns - IP reputation system integration - Common function usage Purpose: - Ensure consistency across all scripts - Quick reference for file locations - Guidelines for adding new features - Testing requirements before commits - Uniform user experience standards This document serves as the single source of truth for development practices and helps maintain code quality as the toolkit grows. https://claude.com/claude-code
2025-11-07 17:49:27 -05:00
parent 11de58beaa
commit 8a2de86418
1 changed files with 606 additions and 0 deletions
@@ -0,0 +1,606 @@
+# Server Management Toolkit - Development Guidelines
+
+**Version:** 2.1.0
+**Last Updated:** 2025-11-07
+
+This document provides uniform standards and quick reference for developing and maintaining the Server Management Toolkit.
+
+---
+
+## Table of Contents
+
+1. [Project Structure & File Map](#project-structure--file-map)
+2. [Script Design Standards](#script-design-standards)
+3. [User Experience Guidelines](#user-experience-guidelines)
+4. [Shared Resources](#shared-resources)
+5. [Testing Guidelines](#testing-guidelines)
+6. [Git Workflow](#git-workflow)
+
+---
+
+## Project Structure & File Map
+
+### Directory Layout
+
+```
+server-toolkit/
+├── launcher.sh                  # Main entry point - menu system
+├── README.md                    # User documentation
+├── DEVELOPMENT-GUIDELINES.md    # This file (developer reference)
+│
+├── lib/                         # Shared libraries (NEVER modify without testing all scripts)
+│   ├── common-functions.sh      # Core utilities (print_*, press_enter, etc.)
+│   ├── system-detect.sh         # OS/cPanel detection (SYS_* variables)
+│   ├── user-manager.sh          # cPanel user functions (select_user_interactive, etc.)
+│   ├── mysql-analyzer.sh        # Database analysis utilities
+│   ├── ip-reputation.sh         # Centralized IP reputation tracking
+│   └── reference-db.sh          # Session-based cross-module intelligence (.sysref)
+│
+├── config/                      # Configuration files
+│   ├── settings.conf            # Main configuration
+│   ├── whitelist-ips.txt        # IP whitelist
+│   └── whitelist-user-agents.txt # User-Agent whitelist
+│
+├── modules/                     # Modular scripts by category
+│   ├── security/                # Security & threat analysis
+│   │   ├── bot-analyzer.sh
+│   │   ├── live-attack-monitor.sh
+│   │   ├── enable-cphulk.sh
+│   │   └── ip-reputation-manager.sh
+│   │
+│   ├── website/                 # Website diagnostics
+│   │   ├── website-error-analyzer.sh
+│   │   ├── 500-error-tracker.sh
+│   │   ├── wordpress-menu.sh    # WordPress submenu
+│   │   └── wordpress/           # WordPress-specific tools
+│   │       └── wordpress-cron-manager.sh
+│   │
+│   ├── backup/                  # Acronis Cyber Protect integration
+│   │   ├── acronis-backup-manager.sh
+│   │   ├── acronis-trigger-backup.sh
+│   │   ├── acronis-agent-status.sh
+│   │   └── [14 other acronis scripts]
+│   │
+│   ├── diagnostics/             # System diagnostics
+│   │   └── system-health-check.sh
+│   │
+│   ├── performance/             # Performance analysis
+│   │   ├── mysql-query-analyzer.sh
+│   │   └── hardware-health-check.sh
+│   │
+│   └── maintenance/             # System maintenance
+│       └── cleanup-toolkit-data.sh
+│
+└── tools/                       # Utility scripts
+    └── diagnostic-report.sh
+```
+
+### Key File Locations Quick Reference
+
+| Resource | Path | Purpose |
+|----------|------|---------|
+| **Main Launcher** | `/root/server-toolkit/launcher.sh` | Menu system entry point |
+| **Reference DB** | `/root/server-toolkit/.sysref` | Session-based intelligence sharing |
+| **Common Functions** | `/root/server-toolkit/lib/common-functions.sh` | Shared utilities all scripts use |
+| **IP Reputation** | `/root/server-toolkit/lib/ip-reputation.sh` | Centralized IP tracking |
+| **User Manager** | `/root/server-toolkit/lib/user-manager.sh` | cPanel user selection |
+| **Website Errors** | `/root/server-toolkit/modules/website/website-error-analyzer.sh` | Intelligent error analysis |
+| **WordPress Cron** | `/root/server-toolkit/modules/website/wordpress/wordpress-cron-manager.sh` | WP cron management |
+| **Security Menu** | Search `show_security_menu` in launcher.sh | 3-tier security structure |
+
+---
+
+## Script Design Standards
+
+### Standard Script Template
+
+Every module script should follow this structure:
+
+```bash
+#!/bin/bash
+
+################################################################################
+# Script Name
+################################################################################
+# Purpose: Clear description of what this script does
+# Features:
+# - Feature 1
+# - Feature 2
+# - Feature 3
+################################################################################
+
+# Determine correct path to root based on script location
+# Example paths:
+#   modules/security/script.sh        → ../../
+#   modules/website/script.sh         → ../../
+#   modules/website/wordpress/script.sh → ../../../
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "$SCRIPT_DIR/lib/common-functions.sh"
+source "$SCRIPT_DIR/lib/system-detect.sh"
+
+# Optional libraries (only include if needed)
+# source "$SCRIPT_DIR/lib/user-manager.sh"
+# source "$SCRIPT_DIR/lib/ip-reputation.sh"
+# source "$SCRIPT_DIR/lib/reference-db.sh"
+
+# Root check
+if [ "$EUID" -ne 0 ]; then
+    print_error "This script must be run as root"
+    exit 1
+fi
+
+# Main script logic starts here
+clear
+print_banner "Script Name"
+
+echo ""
+# ... script functionality ...
+echo ""
+
+press_enter
+```
+
+### Path Resolution Rules
+
+**CRITICAL:** Always verify `SCRIPT_DIR` calculation based on script location:
+
+| Script Location | Correct SCRIPT_DIR |
+|----------------|-------------------|
+| `modules/category/script.sh` | `../../` (up 2 levels) |
+| `modules/category/subcategory/script.sh` | `../../../` (up 3 levels) |
+| `tools/script.sh` | `../` (up 1 level) |
+
+**Test after moving scripts:**
+```bash
+bash /path/to/script.sh  # Should load libraries without errors
+```
+
+---
+
+## User Experience Guidelines
+
+### 1. Cancel/Back Options (MANDATORY)
+
+**Every user input must allow cancellation:**
+
+#### Menu Options
+```bash
+echo "  1) Option One"
+echo "  2) Option Two"
+echo "  3) Option Three"
+echo "  0) Cancel and return to menu"    # REQUIRED
+echo ""
+read -p "Select option: " choice
+
+case $choice in
+    0)
+        echo ""
+        echo "Operation cancelled."
+        echo ""
+        exit 0
+        ;;
+    # ... other options ...
+esac
+```
+
+#### Text Input Prompts
+```bash
+echo -n "Enter domain name (or 0 to cancel): "
+read -r domain
+
+if [ -z "$domain" ] || [ "$domain" = "0" ]; then
+    echo "Operation cancelled."
+    press_enter
+    exit 0
+fi
+```
+
+#### Confirmation Prompts
+```bash
+echo -n "Are you sure? (y/n) [n]: "
+read -r confirm
+
+if [ "$confirm" != "y" ] && [ "$confirm" != "Y" ]; then
+    echo "Operation cancelled."
+    press_enter
+    exit 0
+fi
+```
+
+### 2. Consistent Messaging
+
+Use these standard messages:
+
+```bash
+# Success
+print_success "Operation completed successfully"
+
+# Error
+print_error "Something went wrong"
+
+# Warning
+print_warning "This action cannot be undone"
+
+# Info
+print_info "Processing data..."
+
+# Cancellation
+echo "Operation cancelled."
+```
+
+### 3. Always Use press_enter
+
+**REQUIRED at end of every script:**
+
+```bash
+echo ""
+print_success "Task completed"
+echo ""
+press_enter  # Gives user time to read output before returning to menu
+```
+
+---
+
+## Shared Resources
+
+### 1. Reference Database (.sysref)
+
+**Session-based intelligence sharing between modules**
+
+Location: `/root/server-toolkit/.sysref`
+Purpose: Share discovered information during a single session
+**NOT persistent** - cleared on cleanup
+
+#### Usage:
+
+```bash
+source "$SCRIPT_DIR/lib/reference-db.sh"
+
+# Store WordPress installation
+db_store_wordpress "domain.com" "username" "/home/user/public_html" "wp_db" "wp_user" "6.4" "15" "3"
+
+# Retrieve WordPress installations
+wp_sites=$(db_get_all_wordpress)
+while IFS='|' read -r type domain owner path db_name db_user version plugins themes; do
+    echo "Found: $domain owned by $owner"
+done <<< "$wp_sites"
+
+# Query specific domain
+wp_info=$(db_get_wordpress_by_domain "example.com")
+```
+
+#### Available Functions:
+
+| Function | Purpose |
+|----------|---------|
+| `db_store_wordpress` | Store WP installation details |
+| `db_get_all_wordpress` | Get all WP sites |
+| `db_get_wordpress_by_domain` | Get specific domain |
+| `db_store_user_domain_map` | Map user to domains |
+| `db_get_user_domains` | Get user's domains |
+
+### 2. IP Reputation System
+
+**Centralized IP tracking across all security modules**
+
+Location: `/root/server-toolkit/lib/ip-reputation.sh`
+
+#### Usage:
+
+```bash
+source "$SCRIPT_DIR/lib/ip-reputation.sh"
+
+# Check if IP is a known bot
+if is_known_bot "1.2.3.4"; then
+    echo "This is a bot"
+fi
+
+# Check if IP should be filtered
+if should_filter_ip "1.2.3.4"; then
+    continue  # Skip this IP
+fi
+
+# Log threat detection
+log_ip_threat "1.2.3.4" "SSH brute force" "80"
+
+# Query reputation
+rep_score=$(get_ip_reputation "1.2.3.4")
+```
+
+### 3. User Manager
+
+**Consistent cPanel user selection**
+
+Location: `/root/server-toolkit/lib/user-manager.sh`
+
+#### Usage:
+
+```bash
+source "$SCRIPT_DIR/lib/user-manager.sh"
+
+# Interactive user selection
+select_user_interactive "Select cPanel user to analyze"
+if [ -n "$SELECTED_USER" ]; then
+    echo "Selected: $SELECTED_USER"
+else
+    echo "No user selected"
+    exit 0
+fi
+
+# List all users
+list_all_users
+
+# Get user's domains
+domains=$(get_user_domains "username")
+```
+
+### 4. Common Functions
+
+**Core utilities all scripts use**
+
+Location: `/root/server-toolkit/lib/common-functions.sh`
+
+#### Essential Functions:
+
+```bash
+# Output formatting
+print_banner "My Script Title"
+print_success "Operation completed"
+print_error "Failed to complete"
+print_warning "Proceed with caution"
+print_info "Processing..."
+
+# User interaction
+press_enter  # Wait for user before returning to menu
+
+# Colors (use sparingly, prefer print_* functions)
+echo -e "${GREEN}Success${NC}"
+echo -e "${RED}Error${NC}"
+echo -e "${YELLOW}Warning${NC}"
+```
+
+---
+
+## Testing Guidelines
+
+### Before Committing
+
+**ALWAYS test these scenarios:**
+
+1. **Cancel Functionality**
+   ```bash
+   # Test each user input accepts "0" to cancel
+   bash script.sh
+   # Enter 0 at each prompt
+   # Verify clean exit
+   ```
+
+2. **Path Resolution**
+   ```bash
+   # Verify libraries load correctly
+   bash -n /path/to/script.sh  # Syntax check
+   bash /path/to/script.sh     # Run from anywhere
+   ```
+
+3. **Menu Navigation**
+   ```bash
+   # Navigate: Main → Category → Script → Cancel
+   bash launcher.sh
+   # Select through menus
+   # Cancel and verify return to previous menu
+   ```
+
+4. **Error Handling**
+   ```bash
+   # Test with invalid input
+   # Test with missing files
+   # Test with permission issues
+   ```
+
+### Test Checklist
+
+- [ ] Script loads libraries without errors
+- [ ] All menus have "0) Cancel" option
+- [ ] All text inputs accept "0" to cancel
+- [ ] `press_enter` called at end
+- [ ] `print_banner` used for title
+- [ ] Error messages use `print_error`
+- [ ] Success messages use `print_success`
+- [ ] Root check present
+- [ ] No syntax errors (`bash -n script.sh`)
+- [ ] Works when called from launcher
+- [ ] Works when called directly
+
+---
+
+## Git Workflow
+
+### Commit Message Template
+
+```
+Brief summary of changes (50 chars max)
+
+Changes:
+- Specific change 1
+- Specific change 2
+- Specific change 3
+
+[Optional sections:]
+User Experience Improvements:
+- Improvement 1
+- Improvement 2
+
+Technical Details:
+- Detail 1
+- Detail 2
+
+Tested:
+✓ Test scenario 1
+✓ Test scenario 2
+✓ Test scenario 3
+
+🤖 Generated with Claude Code
+https://claude.com/claude-code
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+### Commit Workflow
+
+```bash
+# 1. Check status
+git status
+
+# 2. Add all changes
+git add -A
+
+# 3. Commit with descriptive message
+git commit -m "$(cat <<'EOF'
+Your commit message here
+EOF
+)"
+
+# 4. Push to remote
+git push origin main
+```
+
+### What to Commit
+
+**DO commit:**
+- Script files (*.sh)
+- Configuration templates
+- Documentation (*.md)
+- Library updates
+
+**DON'T commit:**
+- `.sysref` (session data)
+- `.sysref.timestamp`
+- Temporary files (`/tmp/*`)
+- User-specific configs with credentials
+- Cache files
+
+### Commit Frequency
+
+- After completing a feature
+- After fixing bugs
+- Before major refactoring
+- At end of work session
+
+---
+
+## Menu Structure Standards
+
+### Menu Hierarchy Rules
+
+1. **Main Menu** → Categories (Security, Website, Performance, etc.)
+2. **Category Menu** → Sub-categories or direct scripts
+3. **Sub-Menu** → Specific tools or actions
+4. **Script** → Actual functionality
+
+### Adding New Scripts
+
+#### 1. Create Script in Correct Category
+
+```bash
+# modules/category/new-script.sh
+```
+
+#### 2. Add to Category Menu
+
+Edit `launcher.sh`:
+
+```bash
+# Add to show_category_menu function
+echo "  X) New Script Name  - Description"
+
+# Add to handle_category_menu case statement
+case $choice in
+    X) run_module "category" "new-script.sh" ;;
+esac
+```
+
+#### 3. Update README.md
+
+Add to feature list and structure documentation
+
+---
+
+## Quick Reference
+
+### Common Tasks
+
+| Task | Command/Location |
+|------|------------------|
+| Test script syntax | `bash -n script.sh` |
+| Run specific script | `bash /root/server-toolkit/modules/category/script.sh` |
+| Clear session data | Option 8 in main menu |
+| View logs | Check `/tmp/` for script outputs |
+| Check running shells | `/bashes` command |
+| Force library reload | Re-source in script or restart launcher |
+
+### File Naming Conventions
+
+- Use kebab-case: `my-script-name.sh`
+- Be descriptive: `wordpress-cron-manager.sh` not `wp-cron.sh`
+- Match purpose: `enable-cphulk.sh` clearly states what it does
+
+### Variable Naming
+
+```bash
+# Global constants (UPPERCASE)
+APACHE_LOG_DIR="/var/log/apache2"
+MAX_RETRIES=3
+
+# Local variables (lowercase with underscores)
+domain_name="example.com"
+error_count=0
+
+# Function names (lowercase with underscores)
+check_wp_installation() {
+    # ...
+}
+```
+
+---
+
+## Troubleshooting Development Issues
+
+### Script Can't Find Libraries
+
+**Problem:** `source: file not found`
+
+**Solution:**
+```bash
+# Check SCRIPT_DIR calculation
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+echo "SCRIPT_DIR: $SCRIPT_DIR"
+
+# Verify from script location:
+# modules/category/script.sh → goes up 2 levels
+# modules/category/sub/script.sh → goes up 3 levels
+```
+
+### Menu Option Not Working
+
+**Problem:** Script doesn't launch from menu
+
+**Solution:**
+1. Check `run_module` call in launcher.sh uses correct category and filename
+2. Verify script is executable: `chmod +x script.sh`
+3. Check script has `#!/bin/bash` shebang
+
+### Cancel Not Working
+
+**Problem:** User can't exit from prompt
+
+**Solution:**
+1. Add `0) Cancel` to all menus
+2. Add `(or 0 to cancel)` to all text prompts
+3. Check for empty or "0" input and exit cleanly
+
+---
+
+**Remember:** Consistency is key. Follow these guidelines for every new script and update existing scripts to match these standards as you work on them.
+
+**When in doubt:** Look at `modules/website/wordpress/wordpress-cron-manager.sh` as a reference implementation that follows all standards.