# 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.