matrix

#!/bin/bash
# SiteMatrix - Unified PHP Stack Management Script

set -euo pipefail

# Configuration
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$SCRIPT_DIR"

# Detect if running from frontend/ subdirectory and adjust paths
if [[ "$(basename "$SCRIPT_DIR")" == "frontend" ]]; then
    PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
fi

DOMAIN_SUFFIX="127.0.0.1.nip.io"
COMPOSE_FILE="$PROJECT_ROOT/docker-compose.yml"
DOCKER_COMPOSE="docker-compose"  # Default fallback
# DEFAULT_PHP_VERSION now sourced from config/validation.sh

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

# Detect host LAN IP for user-facing URLs so other devices on the network can connect.
# get_lan_ip / HOST_IP live in scripts/helpers.sh (shared with scripts/*.sh subprocesses).

JSON_OUTPUT=false

output_json() {
    echo "$1"
}

error_json() {
    local code="${1:-}"
    local message="$2"
    printf '{"success":false,"error":{"code":"%s","message":"%s"}}\n' "$code" "$message"
    exit 1
}

check_docker_json() {
    if [[ "$JSON_OUTPUT" == true ]]; then
        if ! $CONTAINER_RUNTIME info >/dev/null 2>&1; then
            error_json "DOCKER_ERROR" "Docker daemon is not running"
        fi
    fi
}

# sanitize_sql_identifier, validate_site_name now sourced from config/validation.sh

# Helper functions
log_info() { echo -e "${BLUE}ℹ️  $1${NC}"; }
log_success() { echo -e "${GREEN}✅ $1${NC}"; }
log_warning() { echo -e "${YELLOW}⚠️  $1${NC}"; }
log_error() { echo -e "${RED}❌ $1${NC}"; }

json_log_override() {
    if [[ "$JSON_OUTPUT" == true ]]; then
        log_info() { :; }
        log_success() { :; }
        log_warning() { :; }
        log_error() { :; }
    fi
}

ACTIVITY_LOG="$PROJECT_ROOT/logs/activity.log"

log_activity() {
    local action="${1:-}"
    local site="${2:-}"
    local details="${3:-}"
    local timestamp
    timestamp=$(date '+%Y-%m-%d %H:%M:%S')
    echo "[$timestamp] $action | $site | $details" >> "$ACTIVITY_LOG"
}


# Load environment
if [[ -f "$PROJECT_ROOT/.env" ]]; then
    set -a
    source "$PROJECT_ROOT/.env"
    set +a
fi

# Use podman-compose instead of docker-compose
# Preset DOCKER_COMPOSE wins (tests/CI inject the stub; without this guard
# sourcing matrix on a compose-less host aborts — same rule as common.sh).
if [[ -z "${DOCKER_COMPOSE:-}" ]]; then
    if command -v podman-compose >/dev/null 2>&1; then
        DOCKER_COMPOSE="podman-compose"
    elif command -v docker-compose >/dev/null 2>&1; then
        DOCKER_COMPOSE="docker-compose"
    else
        log_error "Neither docker-compose nor podman-compose found"
        exit 1
    fi
fi

# Derive container runtime from compose tool
if [[ "$DOCKER_COMPOSE" == "podman-compose" ]]; then
    CONTAINER_RUNTIME="podman"
else
    CONTAINER_RUNTIME="docker"
fi

# Load shared validation rules
source "$PROJECT_ROOT/config/validation.sh"

# Load shared helper functions (stack detection, site lifecycle)
source "$PROJECT_ROOT/scripts/helpers.sh"
source "$PROJECT_ROOT/scripts/presets-lib.sh"
source "$PROJECT_ROOT/scripts/ssl-lib.sh"
source "$PROJECT_ROOT/scripts/doctor-lib.sh"
source "$PROJECT_ROOT/scripts/export-import-lib.sh"
source "$PROJECT_ROOT/scripts/share-lib.sh"
source "$PROJECT_ROOT/scripts/ops-lib.sh"
source "$PROJECT_ROOT/scripts/site-types-lib.sh"

# Load compose manipulation helpers
source "$PROJECT_ROOT/scripts/compose-lib.sh"

# Main help
show_help() {
    cat << EOF
🚀 SiteMatrix — PHP Stack Management

Usage: ./matrix <command> [options]

 Site Management:
   create <name> [--type=wp|laravel|symfony|drupal|joomla|grav] [--php-version=X.X] [--stack=nginx|apache]
               Create new site (default type: wp, PHP: ${DEFAULT_PHP_VERSION}, stack: nginx)
               PHP floors: wp 7.4, joomla/grav 8.1, laravel/symfony 8.2, drupal 8.3
               --wp-version/--multisite/--preset and stack=apache are wp-only
    edit <name> [--php-version=X.X] [--port=XXXX]  Edit site configuration
    rename <old> <new> [--delete-old]  Rename an existing site
    list              List all sites
   start <name>      Start specific site
   stop <name>       Stop specific site
   remove <name>     Remove site
   info <name>       Show site details
   rest <name>       Show WordPress REST API routes for a site (JSON)

 Environment Management:
   install [name]    One-command install (creates site and starts services)
   start             Start all sites, services, and frontend
   stop              Stop all services and frontend
   restart           Restart all services and frontend
   status            Show system status including frontend
   logs [site]       Show logs (all or specific site)
   clean             Clean up unused resources

 Code Quality:
   check [name] [path]   Run code quality checks (all sites or specific site/path)
   test                  Run tests
   fix                   Auto-fix code issues

  Site Maintenance:
    clone <src> <dst> Clone existing site
     reset <name>      Reset site to fresh install
     update <name>     Update WordPress core
     cache <name>      Clear site caches
     search-replace    Database search/replace
     backup <name>     Backup site database/files (--schedule=<interval> --retention=N to schedule)
    cron-install      Install a site's scheduled backup into the crontab
    cron-remove       Remove a site's scheduled backup from the crontab
     optimize [name]   Apply performance optimizations to existing site(s)

  Development:
    shell <service>   Access container shell (wp, db, nginx)
    wp <site> <args>  Run WP-CLI for a site
    url <name>        Show site URLs
    import-db <n> <f> Import SQL dump (site name, file path)
    export-db <n> [f] Export database (site name, optional file)
    frontend <action> Manage frontend (start|stop|restart|status)
    mail             Open Mailpit email testing UI
    phpmyadmin [site] Open phpMyAdmin (optionally preselect a site database)
    xdebug <site>    Enable Xdebug (always on) for site
    scaffold <type> <name> Scaffold theme/plugin (theme|plugin)
    preset <name>    List available site presets
    watch <site>     Watch files and clear OPcache on changes

  System:
    repair [site]     Repair missing configs, containers, and databases
    health            Run system health check
    doctor            Run environment/bootstrap checks (--json supported)
    test              Run compat matrix for a site (--wp-versions=6.4,6.5 --json)
    export            Export a site to a tar.gz bundle (manifest + files + db dump)
    import            Import a site from a tar.gz bundle
    share             Share a running site via cloudflared/ngrok/bore tunnel (--yes)

 Frontend:
   ./matrix start            # Starts frontend at http://$HOST_IP:8500
   ./matrix status           # Shows frontend status
   ./matrix stop             # Stops frontend with other services
   ./matrix token            # Print dashboard LAN token (MATRIX_DASHBOARD_TOKEN)
   ./matrix token --rotate   # Generate a new token (restart to apply)

EOF
}

# Get sites as array (for bash 3.2 compatibility)
get_sites_array() {
    local temp_file=$(mktemp)
    get_sites > "$temp_file"
    echo "$temp_file"
}

# Create new site
create_site() {
    local site_name=""
    local php_version="$DEFAULT_PHP_VERSION"
    local preset="blank"
    local stack="nginx"
    local type="wp"
    local multisite=""
    local wp_version=""
    local skip_download=0

    # Parse arguments
    while [[ $# -gt 0 ]]; do
        case "$1" in
            --skip-download)
                skip_download=1
                shift
                ;;
            --php-version=*)
                php_version="${1#*=}"
                shift
                ;;
            --php-version)
                php_version="$2"
                shift 2
                ;;
            --stack=*)
                stack="${1#*=}"
                shift
                ;;
            --stack)
                stack="$2"
                shift 2
                ;;
            --type=*)
                type="${1#*=}"
                shift
                ;;
            --type)
                type="$2"
                shift 2
                ;;
            --preset=*)
                preset="${1#*=}"
                shift
                ;;
            --preset)
                preset="$2"
                shift 2
                ;;
            --multisite=*)
                multisite="${1#*=}"
                shift
                ;;
            --wp-version=*)
                wp_version="${1#*=}"
                shift
                ;;
            --wp-version)
                wp_version="$2"
                shift 2
                ;;
            --multisite)
                multisite="$2"
                shift 2
                ;;
            -*)
                log_error "Unknown option: $1"
                echo "Usage: ./matrix create <name> [--type=wp|laravel|symfony|drupal|joomla|grav] [--php-version=X.X] [--wp-version=X.X|latest] [--stack=nginx|apache] [--preset=preset-name] [--multisite=subdirectory|subdomain]"
                return 1
                ;;
            *)
                if [[ -z "$site_name" ]]; then
                    site_name="$1"
                fi
                shift
                ;;
        esac
    done
    
    if [[ -z "$site_name" ]]; then
        read -p "Enter site name: " site_name
    fi
    
    if [[ -z "$site_name" ]]; then
        log_error "Site name required"
        return 1
    fi
    validate_site_name "$site_name" || return 1

    validate_php_version "$php_version" || return 1

    if ! validate_site_type "$type"; then
        log_error "Invalid type: $type (use wp, laravel, symfony, drupal, joomla, grav)"
        return 1
    fi

    if [[ "$stack" == "apache" && "$type" != "wp" ]]; then
        log_error "Stack 'apache' is only supported for wp sites (type: $type)"
        return 1
    fi

    local min_php
    min_php=$(site_type_min_php "$type")
    if ! php_at_least "$php_version" "$min_php"; then
        log_error "Type '$type' requires PHP >= $min_php (got $php_version)"
        return 1
    fi

    # WP-only flags rejected for non-wp types
    if [[ "$type" != "wp" ]]; then
        if [[ -n "$wp_version" ]]; then
            log_error "--wp-version is only supported for wp sites (type: $type)"
            return 1
        fi
        if [[ -n "$multisite" ]]; then
            log_error "--multisite is only supported for wp sites (type: $type)"
            return 1
        fi
        if [[ "$preset" != "blank" ]]; then
            log_error "Presets are only supported for wp sites (type: $type)"
            return 1
        fi
    fi

    case "$stack" in
        nginx|apache) ;;
        *)
            log_error "Invalid stack: $stack (use nginx or apache)"
            return 1
            ;;
    esac

    # Validate multisite mode
    if [[ -n "$multisite" ]]; then
        case "$multisite" in
            subdirectory|subdomain) ;;
            *)
                log_error "Invalid multisite mode: $multisite (use subdirectory or subdomain)"
                return 1
                ;;
        esac
    fi

    # Validate + resolve WP version pin
    if [[ -n "$wp_version" ]]; then
        validate_wp_version "$wp_version" || {
            log_error "Invalid WP version: $wp_version (use X.Y like 6.4, or latest)"
            return 1
        }
        wp_version=$(resolve_wp_version "$wp_version")
    fi

    if site_exists "$site_name"; then
        log_error "Site '$site_name' already exists"
        return 1
    fi
    
    local site_dir="$PROJECT_ROOT/wp_$site_name"
    
    log_info "Creating $type site: $site_name (PHP $php_version, stack: $stack)"

    # Create directory
    mkdir -p "$site_dir"
    mkdir -p "$PROJECT_ROOT/logs/wp_$site_name"

    # Provision site files by type.
    #
    # Marker placement differs per type, and the reason is filesystem
    # ownership, not taste:
    #   wp      — markers are written HERE, before the container chowns the tree
    #             to www-data. After that the host user cannot write into the
    #             directory at all (that bug shipped once already).
    #   non-wp  — composer create-project requires an EMPTY target, so markers
    #             must wait until provisioning finishes; by then the tree is
    #             www-data-owned, so provision_site_type writes them from inside
    #             a root container instead (write_markers_in_container).
    if [[ "$type" == "wp" ]]; then
        if [[ "$stack" == "apache" ]]; then
            echo "apache" > "$site_dir/.matrix-stack"
        else
            echo "nginx" > "$site_dir/.matrix-stack"
        fi
        set_site_type "$site_name" "wp"

    # Copy WordPress files using Docker/Podman
    if [[ "$skip_download" -eq 0 ]]; then
        log_info "Installing WordPress (PHP $php_version)..."
        $CONTAINER_RUNTIME run --rm -v "$site_dir":/var/www/html wordpress:php${php_version}-fpm \
            bash -c "cp -a /usr/src/wordpress/. /var/www/html/ && chown -R www-data:www-data /var/www/html"

        # Install WP-CLI in site directory (persists via volume)
        log_info "Installing WP-CLI..."
        $CONTAINER_RUNTIME run --rm -v "$site_dir":/var/www/html wordpress:php${php_version}-fpm \
            bash -c "curl -sO https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar && chmod +x wp-cli.phar && mv wp-cli.phar /var/www/html/wp && chown www-data:www-data /var/www/html/wp"

        # Pin WP core to --wp-version (Phase 7): overlay pinned core over image copy
        if [[ -n "$wp_version" ]]; then
            log_info "Pinning WordPress core to $wp_version..."
            if wp_fetch_core "$wp_version" "$site_dir"; then
                log_success "WordPress $wp_version pinned"
            else
                log_warning "WP core pin to $wp_version failed; keeping image default"
            fi
        fi
    else
        log_info "Skipping WP download (--skip-download: files restored from bundle)"
    fi
    elif [[ "$skip_download" -eq 1 ]]; then
        # --skip-download means "restore files from a bundle" for every type, not
        # just wp — otherwise import re-runs composer create-project and then
        # overwrites every file it just wrote.
        log_info "Skipping provisioning (--skip-download: files restored from bundle)"
    else
        # Non-wp types: shared matrix-php runtime image + per-type provisioning.
        # provision_site_type also writes .matrix-stack/.matrix-type from inside
        # a root container (see the marker-placement note above).
        build_site_image "$php_version" || { rollback_site_create "$site_name"; return 1; }
        provision_site_type "$site_name" "$type" "$php_version" "$stack" \
            || { rollback_site_create "$site_name"; return 1; }
    fi

    # wp with --skip-download: no container chowns the tree, so the markers
    # written above are all that is needed.

    # Copy baseline performance optimization files (wp only)
    if [[ "$type" == "wp" && -d "$PROJECT_ROOT/config/optimizations" ]]; then
        log_info "Applying performance optimizations..."
        mkdir -p "$site_dir/wp-content/mu-plugins"
        cp "$PROJECT_ROOT/config/optimizations/perf-mu-plugin.php" "$site_dir/wp-content/mu-plugins/"
        cp "$PROJECT_ROOT/config/optimizations/object-cache.php" "$site_dir/wp-content/object-cache.php"
    fi

    # Apply preset if not blank (wp only — enforced above)
    if [[ "$preset" != "blank" ]]; then
        apply_preset "$site_name" "$preset" || return 1
    fi

    # Create site-specific nginx configuration (nginx stack only)
    local nginx_conf_path="$PROJECT_ROOT/config/nginx/$site_name.conf"
    if [[ "$stack" == "nginx" ]]; then
        generate_nginx_conf "$site_name" "$type"
    fi

    if [[ ! -f "$COMPOSE_FILE" ]]; then
        log_warning "docker-compose.yml missing - recreating base file before adding site"
        rebuild_compose_base
    fi

    port=$(get_next_port)
    compose_add_site "$site_name" "$php_version" "$port" "$nginx_conf_path" "$stack" "$type"

    # Create database and grant permissions (all types except grav)
    if site_type_uses_db "$type" && compose_or_container_running "wp_db"; then
        $CONTAINER_RUNTIME exec -e MYSQL_PWD="${MYSQL_ROOT_PASSWORD:-root}" wp_db mysql -u root \
            -e "CREATE DATABASE IF NOT EXISTS \`${site_name}_db\`; GRANT ALL PRIVILEGES ON \`${site_name}_db\`.* TO '${MYSQL_USER:-wp_user}'@'%'; FLUSH PRIVILEGES;" 2>/dev/null || true
    fi

    log_success "Site '$site_name' created successfully with PHP $php_version ($stack, type: $type)"
    log_activity "CREATE" "$site_name" "Created with PHP $php_version, stack $stack, port $port, type $type"
    echo "Direct: http://$HOST_IP:$port"
    echo "Database: http://$HOST_IP:8200"
    if [[ "$type" == "joomla" ]]; then
        # Joomla's first-visit wizard asks for DB creds — print them for easy copy
        echo "Joomla wizard DB: ${site_name}_db / user: ${MYSQL_USER:-wp_user} / password: ${MYSQL_PASSWORD:-wp_password}"
    fi

    # Auto-start the site after creation
    log_info "Starting site '$site_name'..."
    if [[ "$stack" == "apache" ]]; then
        matrix_site_build_if_apache "$site_name" || return 1
    fi
    matrix_site_up "$site_name"

    # Apply runtime performance tweaks (wp-config constants, phpredis, etc.)
    [[ "$type" == "wp" ]] && apply_performance_tweaks "$site_name" "$php_version"

    # Laravel: stock create-project runs migrations against the default .env
    # (sqlite), which we then repoint at MySQL — the tables would be missing
    # and first visit 500s. Migrate after start, when the DB exists.
    # --skip-download (import) skips this: the bundle restore brings its own db.
    if [[ "$type" == "laravel" && "$skip_download" -eq 0 ]] && compose_or_container_running "wp_db"; then
        log_info "Running Laravel migrations..."
        if $CONTAINER_RUNTIME exec -w /var/www/html "wp_$site_name" php artisan migrate --force >/dev/null 2>&1; then
            log_success "Laravel migrations applied"
        else
            log_warning "Migrations not applied — run: $CONTAINER_RUNTIME exec wp_$site_name php artisan migrate"
        fi
    fi

    log_success "Site '$site_name' started and ready!"
    log_activity "START" "$site_name" "Auto-started after creation"
}

# Reload the PHP-FPM master process so a newly enabled extension (e.g. phpredis)
# is picked up by running workers. No-op if FPM isn't running. Finds the master
# via its args so it works whether FPM is PID 1 (official *-fpm images) or not
# (the apache stack, where apache is PID 1).
reload_fpm() {
    local container="${1:-}"
    [[ -z "$container" ]] && return 0
    $CONTAINER_RUNTIME exec "$container" bash -c '
        pid=$(ps -eo pid,args 2>/dev/null | grep "php-fpm: master" | grep -v grep | awk "{print \$1}" | head -1)
        if [ -n "$pid" ]; then
            kill -USR2 "$pid" 2>/dev/null && echo "reloaded FPM (pid $pid)"
        fi
    ' 2>/dev/null || true
}

# Apply runtime performance tweaks to a running site's container.
# Installs phpredis (if missing) and appends performance constants to
# wp-config.php.  Safe to re-run on existing sites.
apply_performance_tweaks() {
    local site="${1:-}"
    local php_version="${2:-$DEFAULT_PHP_VERSION}"
    local container="wp_$site"

    if ! $CONTAINER_RUNTIME ps --format '{{.Names}}' 2>/dev/null | grep -q "^$container$"; then
        log_warning "Container $container not running — skipping runtime tweaks"
        return 0
    fi

    # Install phpredis if missing (official Docker images don't bundle it)
    local has_redis
    has_redis=$($CONTAINER_RUNTIME exec "$container" php -m 2>/dev/null | grep -c "^redis$" || true)
    if [[ "$has_redis" -eq 0 ]]; then
        log_info "Installing phpredis in $container..."
        # phpredis >=6 needs PHP 8.x; pin the last 5.x release for PHP 7.x.
        local redis_pkg="redis"
        [[ "$php_version" == 7.* ]] && redis_pkg="redis-5.3.7"
        $CONTAINER_RUNTIME exec "$container" bash -c "
            pecl install $redis_pkg 2>/dev/null && docker-php-ext-enable redis 2>/dev/null
        " || log_warning "phpredis install failed (non-fatal)"
        # Reload FPM so the newly enabled extension is loaded by running workers.
        reload_fpm "$container"
    fi

    # Append performance constants to wp-config.php (idempotent)
    log_info "Adding performance constants to wp-config.php..."
    $CONTAINER_RUNTIME exec "$container" bash -c "
        if ! grep -q 'Matrix performance' wp-config.php 2>/dev/null; then
            cat >> wp-config.php << PHPEOF

// Matrix performance tweaks (applied by apply_performance_tweaks)
if ( ! defined( 'WP_CACHE' ) )           define( 'WP_CACHE', true );
if ( ! defined( 'WP_POST_REVISIONS' ) )   define( 'WP_POST_REVISIONS', 5 );
if ( ! defined( 'EMPTY_TRASH_DAYS' ) )    define( 'EMPTY_TRASH_DAYS', 7 );
if ( ! defined( 'DISABLE_WP_CRON' ) )     define( 'DISABLE_WP_CRON', true );
if ( ! defined( 'WP_MEMORY_LIMIT' ) )     define( 'WP_MEMORY_LIMIT', '256M' );
if ( ! defined( 'WP_MAX_MEMORY_LIMIT' ) ) define( 'WP_MAX_MEMORY_LIMIT', '512M' );
if ( ! defined( 'WP_CACHE_KEY_SALT' ) )   define( 'WP_CACHE_KEY_SALT', '$site' );
if ( ! defined( 'WP_REDIS_HOST' ) )       define( 'WP_REDIS_HOST', 'redis' );
PHPEOF
        fi
    " 2>/dev/null || log_warning "Could not update wp-config.php (container may not be fully booted)"

    log_success "Performance tweaks applied to $site"
}

# Apply performance optimizations to one or all existing sites.
# Usage: optimize_site [site-name]
optimize_site() {
    local target="${1:-}"

    if [[ -n "$target" ]]; then
        require_site_type "$target" wp || return 1
        # propagate optimize_single_site's status (it ran before this branch)
        optimize_single_site "$target"
        return $?
    fi

    log_info "Optimizing all existing sites..."
    local temp_file
    temp_file=$(get_sites_array)
    local skipped=0
    while IFS= read -r site; do
        [[ -z "$site" ]] && continue
        # get_site_type only — require_site_type would log a per-site error
        # right before the summary line below.
        if [[ "$(get_site_type "$site")" != "wp" ]]; then
            skipped=$((skipped + 1))
            continue
        fi
        optimize_single_site "$site"
    done < "$temp_file"
    rm -f "$temp_file"
    [[ "$skipped" -gt 0 ]] && log_info "Skipped $skipped non-wp site(s) (optimize is WordPress-only)"
    return 0
}

optimize_single_site() {
    local site="$1"
    local site_dir="$PROJECT_ROOT/wp_$site"

    if [[ ! -d "$site_dir" ]]; then
        log_error "Site '$site' not found at $site_dir"
        return 1
    fi

    log_info "Optimizing site: $site"

    # Copy optimization files
    if [[ -d "$PROJECT_ROOT/config/optimizations" ]]; then
        mkdir -p "$site_dir/wp-content/mu-plugins"
        cp "$PROJECT_ROOT/config/optimizations/perf-mu-plugin.php" "$site_dir/wp-content/mu-plugins/"
        cp "$PROJECT_ROOT/config/optimizations/object-cache.php" "$site_dir/wp-content/object-cache.php"
        log_success "Optimization files copied to $site"
    else
        log_warning "config/optimizations directory not found — skipping file copy"
    fi

    # Apply runtime tweaks (container must be running)
    local container="wp_$site"
    if $CONTAINER_RUNTIME ps --format '{{.Names}}' 2>/dev/null | grep -q "^$container$"; then
        # Detect PHP version from the container image
        local php_version
        php_version=$($CONTAINER_RUNTIME exec "$container" php -r 'echo PHP_MAJOR_VERSION . "." . PHP_MINOR_VERSION;' 2>/dev/null || echo "$DEFAULT_PHP_VERSION")
        apply_performance_tweaks "$site" "$php_version"
    else
        log_warning "Container $container not running — start the site to apply runtime tweaks (phpredis + wp-config constants)"
        echo "  ./matrix start $site && ./matrix optimize $site"
    fi
}

# Backup site
# Restore site
restore_site() {
    local site_name="${1:-}"
    local backup_file="${2:-}"
    
    if [[ -z "$site_name" || -z "$backup_file" ]]; then
        log_error "Usage: ./matrix restore <site-name> <backup-file>"
        return 1
    fi
    validate_site_name "$site_name" || return 1
    
    if [[ ! -f "$backup_file" ]]; then
        log_error "Backup file not found: $backup_file"
        return 1
    fi
    
    # Verify backup integrity before making any changes
    if ! tar -tzf "$backup_file" >/dev/null 2>&1; then
        log_error "Backup file is corrupt or invalid: $backup_file"
        return 1
    fi
    
    log_info "Restoring site '$site_name' from backup..."
    
    # Stop the site if running
    matrix_site_stop "$site_name"
    
    # Remove existing site files (ownership-safe for www-data-owned trees)
    remove_site_dir "$PROJECT_ROOT/wp_$site_name" "$site_name" || return 1
    
    # Extract backup
    if ! tar -xzf "$backup_file" -C "$PROJECT_ROOT"; then
        log_error "Failed to extract backup file"
        return 1
    fi
    
    # Restore database if SQL dump exists in backup
    local db_dump="$PROJECT_ROOT/wp_$site_name/database.sql"
    if [[ -f "$db_dump" ]] && compose_or_container_running "wp_db"; then
        log_info "Restoring database..."
        $CONTAINER_RUNTIME exec -e MYSQL_PWD="${MYSQL_ROOT_PASSWORD:-root}" wp_db \
            mysql -u root "${site_name}_db" < "$db_dump" 2>/dev/null
        if [[ $? -eq 0 ]]; then
            log_success "Database restored"
        else
            log_warning "Database restore failed — you may need to import manually"
        fi
    fi
    
    # Start the site
    matrix_site_up "$site_name"
    
    log_success "Site '$site_name' restored"
}

list_sites_json() {
    check_docker_json

    local sites_json=""
    local first_site=true

    # Get sites via temp file (bash 3.2 compatible)
    local sites_tmp
    sites_tmp=$(mktemp)
    get_sites > "$sites_tmp"
    local site_list
    site_list=$(cat "$sites_tmp")
    rm -f "$sites_tmp"

    while IFS= read -r site || [[ -n "$site" ]]; do
        [[ -z "$site" ]] && continue
        local status="stopped"
        local port=""

        if compose_or_container_running "wp_$site"; then
            status="running"
        fi

        port=$(get_site_port "$site")

        local php_version
        php_version=$(get_site_php_version_from_compose "$site")

        local stack
        stack=$(get_site_stack "$site")

        local site_type
        site_type=$(get_site_type "$site")

        local container_id=""
        if [[ "$status" == "running" ]]; then
            container_id=$($CONTAINER_RUNTIME ps -q -f "name=^/wp_${site}\$" 2>/dev/null | head -1)
            [[ -z "$container_id" ]] && container_id=$($CONTAINER_RUNTIME ps -q -f name="wp_$site" 2>/dev/null | head -1)
        fi

        local local_url="null"
        if [[ -n "$port" ]]; then
            local_url="\"http://$HOST_IP:$port\""
        fi

        local disk_usage="null"
        if [[ -d "$PROJECT_ROOT/wp_$site" ]]; then
            disk_usage="\"$(du -sh "$PROJECT_ROOT/wp_$site" 2>/dev/null | cut -f1)\""
        fi

        local php_version_json="null"
        if [[ -n "$php_version" ]]; then
            php_version_json="\"$php_version\""
        fi

        local container_id_json="null"
        if [[ -n "$container_id" ]]; then
            container_id_json="\"$container_id\""
        fi

        local site_entry="{\"name\":\"$site\",\"status\":\"$status\",\"stack\":\"$stack\",\"type\":\"$site_type\",\"port\":${port:-null},\"phpVersion\":$php_version_json,\"containerId\":$container_id_json,\"localUrl\":$local_url,\"diskUsage\":$disk_usage}"

        if [[ "$first_site" == true ]]; then
            sites_json="$site_entry"
            first_site=false
        else
            sites_json="$sites_json,$site_entry"
        fi
    done <<< "$site_list"

    # Build services JSON
    local services_json=""
    local first_svc=true

    local svc_names=("wp_db:Database:null" "wp_redis:Redis Cache:null" "wp_phpmyadmin:phpMyAdmin:8200" "wp_phpcs:PHP CodeSniffer:null" "wp_phpstan:PHPStan:null" "wp_cli:WP-CLI:null")
    for svc in "${svc_names[@]}"; do
        local svc_container="${svc%%:*}"
        local remaining="${svc#*:}"
        local svc_name="${remaining%%:*}"
        local svc_port="${remaining##*:}"
        local svc_status="stopped"
        local svc_cid="null"

        if $CONTAINER_RUNTIME ps -q -f name="$svc_container" 2>/dev/null | grep -q .; then
            svc_status="running"
            svc_cid="\"$($CONTAINER_RUNTIME ps -q -f name="$svc_container" 2>/dev/null | head -1)\""
        fi

        local svc_url="null"
        if [[ "$svc_port" != "null" && -n "$svc_port" ]]; then
            svc_url="\"http://$HOST_IP:$svc_port\""
        fi

        local svc_entry="{\"name\":\"$svc_name\",\"status\":\"$svc_status\",\"containerId\":$svc_cid,\"localUrl\":$svc_url}"

        if [[ "$first_svc" == true ]]; then
            services_json="$svc_entry"
            first_svc=false
        else
            services_json="$services_json,$svc_entry"
        fi
    done

    output_json "{\"success\":true,\"sites\":[$sites_json],\"services\":[$services_json]}"
}

# Get port from running container

# List all sites and services
list_sites() {
    log_info "Sites & Services:"
    echo ""

    # Get WordPress sites - use temp file for bash 3.2 compatibility
    local sites_tmp
    sites_tmp=$(mktemp)
    get_sites > "$sites_tmp"
    local site_list
    site_list=$(cat "$sites_tmp")
    rm -f "$sites_tmp"

    # Show WordPress sites
    if [[ -n "$site_list" ]]; then
        printf "%-15s %-10s %-8s %-30s %-30s\n" "WordPress Site" "Status" "Stack" "Local URL" "Domain URL"
        echo "────────────────────────────────────────────────────────────────────────────────────"

        while IFS= read -r site || [[ -n "$site" ]]; do
            [[ -z "$site" ]] && continue
            local status="Stopped"
            local port=""
            local stack
            stack=$(get_site_stack "$site")

            if compose_or_container_running "wp_$site"; then
                status="Running"
            fi

            port=$(get_site_port "$site")

            local port_str="Not configured"
            if [[ -n "$port" ]]; then
                port_str="http://$HOST_IP:$port"
            fi
            printf "%-15s %-10s %-8s %-30s %-30s\n" "$site" "$status" "$stack" \
                "$port_str" \
                "Direct port access only"
        done <<< "$site_list"
        echo ""
    fi
    
    # Show Management Services
    printf "%-15s %-10s %-30s %-30s\n" "Service" "Status" "Local URL" "Description"
    echo "────────────────────────────────────────────────────────────────────────"
    
    # Database
    local db_status="Stopped"
    if compose_or_container_running "wp_db"; then
        db_status="Running"
    fi
    printf "%-15s %-10s %-30s %-30s\n" "Database" "$db_status" \
        "http://$HOST_IP:3306" \
        "MySQL Database Server"
    
    # Redis Cache
    local redis_status="Stopped"
    if compose_or_container_running "wp_redis"; then
        redis_status="Running"
    fi
    printf "%-15s %-10s %-30s %-30s\n" "Redis Cache" "$redis_status" \
        "Internal" \
        "In-memory Cache"
    
    # phpMyAdmin
    local phpmyadmin_status="Stopped"
    if compose_or_container_running "wp_phpmyadmin"; then
        phpmyadmin_status="Running"
    fi
    printf "%-15s %-10s %-30s %-30s\n" "phpMyAdmin" "$phpmyadmin_status" \
        "http://$HOST_IP:8200" \
        "Database Management"

    # Mailpit
    local mailpit_status="Stopped"
    if compose_or_container_running "wp_mailpit"; then
        mailpit_status="Running"
    fi
    printf "%-15s %-10s %-30s %-30s\n" "Mailpit" "$mailpit_status" \
        "http://$HOST_IP:8025" \
        "Email Testing (SMTP: 1025)"


    # Code Quality Tools
    local phpcs_status="Stopped"
    if compose_or_container_running "wp_phpcs"; then
        phpcs_status="Running"
    fi
    printf "%-15s %-10s %-30s %-30s\n" "PHP CodeSniffer" "$phpcs_status" \
        "Tools Profile" \
        "Code Quality - WordPress Standards"
    
    local phpstan_status="Stopped"
    if compose_or_container_running "wp_phpstan"; then
        phpstan_status="Running"
    fi
    printf "%-15s %-10s %-30s %-30s\n" "PHPStan" "$phpstan_status" \
        "Tools Profile" \
        "Code Quality - Static Analysis"
    
    local wpcli_status="Stopped"
    if compose_or_container_running "wp_cli"; then
        wpcli_status="Running"
    fi
    printf "%-15s %-10s %-30s %-30s\n" "WP-CLI" "$wpcli_status" \
        "Tools Profile" \
        "WordPress Command Line"
    
    echo ""
}

# Start a single site: compose up when the site is known to compose,
# otherwise start its existing containers directly (stale/missing compose).
cmd_start_site() {
    local site_name="$1"

    log_info "Starting site '$site_name'..."

    if [[ "$(site_state "$site_name" | sed -n 's/^present=//p')" == "1" ]]; then
        matrix_site_up "$site_name"
    else
        if $CONTAINER_RUNTIME ps -a --format "{{.Names}}" 2>/dev/null | grep -q "^wp_${site_name}$"; then
            $CONTAINER_RUNTIME start "wp_${site_name}" 2>/dev/null || true
        fi
        if site_has_nginx "$site_name" && $CONTAINER_RUNTIME ps -a --format "{{.Names}}" 2>/dev/null | grep -q "^nginx_${site_name}$"; then
            $CONTAINER_RUNTIME start "nginx_${site_name}" 2>/dev/null || true
        fi
    fi

    log_success "Site '$site_name' started"
    log_activity "START" "$site_name" "Started manually"
    show_urls "$site_name"
}

# Start environment
start_env() {
    log_info "Starting environment..."
    $DOCKER_COMPOSE up -d db redis phpmyadmin 2>/dev/null || true
    sleep 3

    # Start frontend if available
    if [[ -d "$PROJECT_ROOT/frontend" ]]; then
        manage_frontend start
    fi

    log_success "Environment started"
    echo ""
    echo "Core services running: database, redis, phpMyAdmin"
    echo ""
    echo "Start sites individually: ./matrix start <site>"
    
    # Show frontend URL
    if [[ -f "$PROJECT_ROOT/.frontend.pid" ]]; then
        local pid=$(cat "$PROJECT_ROOT/.frontend.pid")
        if ps -p "$pid" > /dev/null 2>&1; then
            echo "Frontend: http://$HOST_IP:8500"
        fi
    fi
}

# Stop environment
stop_env() {
    log_info "Stopping environment..."
    
    # Stop frontend first if running
    if [[ -d "$PROJECT_ROOT/frontend" ]]; then
        manage_frontend stop
    fi
    
    $DOCKER_COMPOSE down
    log_success "Environment stopped"
}

show_status_json() {
    check_docker_json

    local containers_json=""
    local first=true

    local compose_output
    compose_output=$($CONTAINER_RUNTIME ps --format "{{.Names}}\t{{.Status}}\t{{.Ports}}" 2>&1) || {
        error_json "DOCKER_ERROR" "Failed to query Docker: $compose_output"
    }

    while IFS=$'\t' read -r name status ports; do
        [[ -z "$name" ]] && continue
        [[ "$name" =~ ^wordpress-matrix ]] && continue
        
        local name_json="${name//\"/\\\"}"
        local status_json="${status//\"/\\\"}"
        local ports_json="${ports//\"/\\\"}"

        local entry="{\"name\":\"$name_json\",\"status\":\"$status_json\",\"ports\":\"$ports_json\"}"

        if [[ "$first" == true ]]; then
            containers_json="$entry"
            first=false
        else
            containers_json="$containers_json,$entry"
        fi
    done <<< "$compose_output"

    # Frontend status
    local fe_status="stopped"
    local fe_pid="null"
    local fe_url="null"
    if [[ -f "$PROJECT_ROOT/.frontend.pid" ]]; then
        local pid=$(cat "$PROJECT_ROOT/.frontend.pid")
        if ps -p "$pid" > /dev/null 2>&1; then
            fe_status="running"
            fe_pid="$pid"
            fe_url="\"http://$HOST_IP:8500\""
        fi
    fi

    output_json "{\"success\":true,\"containers\":[$containers_json],\"frontend\":{\"name\":\"frontend\",\"status\":\"$fe_status\",\"pid\":$fe_pid,\"url\":$fe_url}}"
}

# Whole-environment status: compose table when the compose file exists,
# live container table otherwise.
show_compose_or_live_status() {
    if [[ -f "$COMPOSE_FILE" ]]; then
        $DOCKER_COMPOSE ps
    else
        log_warning "docker-compose.yml missing; showing running containers directly"
        $CONTAINER_RUNTIME ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" 2>/dev/null || true
    fi
}

# Show status
show_status() {
    log_info "System Status:"
    echo ""
    show_compose_or_live_status
    echo ""
    
    # Show frontend status if available
    if [[ -d "$PROJECT_ROOT/frontend" ]]; then
        manage_frontend status 2>/dev/null || echo "Frontend: Unknown"
    fi
    
    list_sites
}

# Print input newest-first (show_logs presents tail output in reverse order)
reverse_lines() {
    perl -e 'print reverse <>'
}

# Compose service logs, falling back to the named container when
# docker-compose.yml is missing. One seam for the per-service ladder.
service_logs() {
    local svc="$1"
    local container="$2"

    if [[ -f "$COMPOSE_FILE" ]]; then
        $DOCKER_COMPOSE logs --tail=100 "$svc" 2>/dev/null | reverse_lines
    else
        $CONTAINER_RUNTIME logs --tail=100 "$container" 2>&1 | reverse_lines
    fi
}

# Site logs: compose first, then live wp_<site> / nginx_<site> containers.
site_logs() {
    local site="$1"
    local log_services
    log_services=$(compose_site_service_names "$site")

    if $DOCKER_COMPOSE logs --tail=100 $log_services 2>/dev/null | grep -q .; then
        $DOCKER_COMPOSE logs --tail=100 $log_services 2>/dev/null | reverse_lines
        return
    fi

    if container_is_running "wp_$site"; then
        $CONTAINER_RUNTIME logs --tail=100 "wp_$site" 2>&1 | reverse_lines
    elif site_has_nginx "$site" && container_is_running "nginx_$site"; then
        $CONTAINER_RUNTIME logs --tail=100 "nginx_$site" 2>&1 | reverse_lines
    else
        log_error "No containers found for site: $site"
    fi
}

# Show logs (newest first)
show_logs() {
    local service="${1:-}"

    case "$service" in
        "")
            if [[ -f "$COMPOSE_FILE" ]]; then
                $DOCKER_COMPOSE logs --tail=100 | reverse_lines
            else
                $CONTAINER_RUNTIME ps --format "{{.Names}}" 2>/dev/null | while read -r container; do
                    [[ -z "$container" ]] && continue
                    echo "==> $container <=="
                    $CONTAINER_RUNTIME logs --tail=50 "$container" 2>&1 || true
                done | reverse_lines
            fi
            ;;
        db)
            service_logs "db" "wp_db"
            ;;
        nginx)
            local nginx_container
            nginx_container=$(compose_ps_names | grep "^nginx_" | head -1)
            if [[ -z "$nginx_container" ]]; then
                nginx_container=$($CONTAINER_RUNTIME ps --format "{{.Names}}" 2>/dev/null | grep "^nginx_" | head -1)
            fi
            if [[ -z "$nginx_container" ]]; then
                log_error "No nginx containers running"
                return
            fi
            if [[ -f "$COMPOSE_FILE" ]]; then
                $DOCKER_COMPOSE logs --tail=100 "$nginx_container" 2>/dev/null | reverse_lines || \
                $CONTAINER_RUNTIME logs --tail=100 "$nginx_container" 2>&1 | reverse_lines
            else
                $CONTAINER_RUNTIME logs --tail=100 "$nginx_container" 2>&1 | reverse_lines
            fi
            ;;
        redis|cache)
            service_logs "redis" "wp_redis"
            ;;
        phpmyadmin|pma)
            service_logs "phpmyadmin" "wp_phpmyadmin"
            ;;
        *)
            site_logs "$service"
            ;;
    esac
}

# Remove site
remove_site() {
    local site_name="${1:-}"
    local force_yes="${2:-}"

    validate_site_name "$site_name" || return 1

    if ! site_exists "$site_name"; then
        log_error "Site '$site_name' not found"
        return 1
    fi

    if [[ "$force_yes" != "--yes" && "$force_yes" != "-y" ]]; then
        echo -e "${RED}WARNING: This will permanently delete '$site_name'${NC}"
        read -p "Continue? [y/N]: " confirm

        if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
            log_info "Cancelled"
            return
        fi
    fi

    log_info "Removing site '$site_name'..."

    # Stop services
    matrix_site_stop "$site_name"
    matrix_site_rm_containers "$site_name"
    $CONTAINER_RUNTIME ps -a --filter name="$site_name" --format '{{.Names}}' 2>/dev/null | while read -r c; do
        $CONTAINER_RUNTIME rm -f "$c" 2>/dev/null || true
    done

    # Remove files (ownership-safe: provisioned trees are www-data-owned,
    # remove_site_dir reclaims them first when plain rm fails)
    remove_site_dir "$PROJECT_ROOT/wp_$site_name" "$site_name" || return 1
    rm -rf "$PROJECT_ROOT/logs/wp_$site_name"

    # Remove database and user
    if compose_or_container_running "wp_db"; then
        $CONTAINER_RUNTIME exec -e MYSQL_PWD="${MYSQL_ROOT_PASSWORD:-root}" wp_db mysql -u root \
            -e "DROP DATABASE IF EXISTS \`${site_name}_db\`; REVOKE ALL PRIVILEGES ON \`${site_name}_db\`.* FROM '${MYSQL_USER:-wp_user}'@'%'; DROP USER IF EXISTS '${MYSQL_USER:-wp_user}'@'%'; CREATE USER IF NOT EXISTS '${MYSQL_USER:-wp_user}'@'%' IDENTIFIED BY '${MYSQL_PASSWORD:-wp_password}'; GRANT ALL PRIVILEGES ON *.* TO '${MYSQL_USER:-wp_user}'@'%'; FLUSH PRIVILEGES;" 2>/dev/null || true
    fi

    compose_remove_site "$site_name"

    # Remove from .env file
    if [[ -f "$PROJECT_ROOT/.env" ]]; then
        local env_var_name=$(echo "$site_name" | tr '[:lower:]' '[:upper:]' | tr '-' '_')
        local temp_env=$(mktemp)
        grep -v "^${env_var_name}_PORT=" "$PROJECT_ROOT/.env" > "$temp_env"
        # Also remove the comment line that identifies the site
        grep -v "^# Site: $site_name" "$temp_env" > "$PROJECT_ROOT/.env"
        rm -f "$temp_env"
    fi

    log_success "Site '$site_name' removed"
    log_activity "REMOVE" "$site_name" "Site removed"
}

# Edit site configuration
edit_site() {
    local site_name=""
    local new_php_version=""
    local new_port=""
    local new_memory=""
    local new_cpu=""

    while [[ $# -gt 0 ]]; do
        case "$1" in
            --php-version=*)
                new_php_version="${1#*=}"
                shift
                ;;
            --php-version)
                new_php_version="$2"
                shift 2
                ;;
            --port=*)
                new_port="${1#*=}"
                shift
                ;;
            --port)
                new_port="$2"
                shift 2
                ;;
            --memory=*)
                new_memory="${1#*=}"
                shift
                ;;
            --memory)
                new_memory="$2"
                shift 2
                ;;
            --cpu=*)
                new_cpu="${1#*=}"
                shift
                ;;
            --cpu)
                new_cpu="$2"
                shift 2
                ;;
            -*)
                log_error "Unknown option: $1"
                echo "Usage: ./matrix edit <name> [--php-version=X.X] [--port=XXXX] [--memory=512M] [--cpu=0.5]"
                return 1
                ;;
            *)
                if [[ -z "$site_name" ]]; then
                    site_name="$1"
                fi
                shift
                ;;
        esac
    done

    if [[ -z "$site_name" ]]; then
        log_error "Usage: ./matrix edit <name> [--php-version=X.X] [--port=XXXX] [--memory=512M] [--cpu=0.5]"
        return 1
    fi
    validate_site_name "$site_name" || return 1

    if ! site_exists "$site_name"; then
        log_error "Site '$site_name' not found"
        return 1
    fi

    local has_changes=false

    if [[ -n "$new_php_version" ]]; then
        validate_php_version "$new_php_version" || return 1
    fi

    # Validate port if provided
    if [[ -n "$new_port" ]]; then
        if ! [[ "$new_port" =~ ^[0-9]+$ ]] || [[ "$new_port" -lt 1024 ]] || [[ "$new_port" -gt 65535 ]]; then
            log_error "Invalid port: $new_port. Must be between 1024 and 65535"
            return 1
        fi
    fi

    # Validate memory if provided
    if [[ -n "$new_memory" ]]; then
        if ! [[ "$new_memory" =~ ^[0-9]+[MmGg]$ ]]; then
            log_error "Invalid memory: $new_memory. Use format like 512M or 1G"
            return 1
        fi
    fi

    # Validate CPU if provided
    if [[ -n "$new_cpu" ]]; then
        if ! [[ "$new_cpu" =~ ^[0-9]*\.?[0-9]+$ ]]; then
            log_error "Invalid CPU: $new_cpu. Use format like 0.5 or 1.0"
            return 1
        fi
    fi

    # Get current PHP version from docker-compose.yml
    local current_php_version=""
    if site_in_compose "$site_name"; then
        current_php_version=$(get_site_php_version_from_compose "$site_name")
        [[ -n "$current_php_version" ]] && current_php_version="php${current_php_version}"
    fi

    # Get current port from docker-compose.yml
    local current_port=""
    if site_in_compose "$site_name"; then
        current_port=$(get_site_port_from_compose "$site_name")
    fi

    # Get current resources
    local current_memory=""
    local current_cpu=""
    local current_nginx_memory=""
    local current_nginx_cpu=""
    if site_in_compose "$site_name"; then
        current_memory=$(grep -A 20 "wp_$site_name:" "$COMPOSE_FILE" | grep "mem_limit:" | head -1 | awk '{print $2}' || true)
        current_cpu=$(grep -A 20 "wp_$site_name:" "$COMPOSE_FILE" | grep "^[[:space:]]*cpus:" | head -1 | awk '{print $2}' || true)
        current_nginx_memory=$(grep -A 20 "nginx_$site_name:" "$COMPOSE_FILE" | grep "mem_limit:" | head -1 | awk '{print $2}' || true)
        current_nginx_cpu=$(grep -A 20 "nginx_$site_name:" "$COMPOSE_FILE" | grep "^[[:space:]]*cpus:" | head -1 | awk '{print $2}' || true)
    fi

    if [[ -z "$current_php_version" && -z "$new_port" && -z "$new_memory" && -z "$new_cpu" ]]; then
        log_error "Site '$site_name' is not configured in docker-compose.yml"
        return 1
    fi

    if site_in_compose "$site_name"; then
        if [[ -n "$new_php_version" ]]; then
            compose_edit_php_version "$site_name" "$new_php_version" || return 1
        fi

        if [[ -n "$new_port" ]]; then
            compose_edit_port "$site_name" "$new_port" || return 1
        fi

        if [[ -n "$new_memory" ]]; then
            compose_edit_memory "$site_name" "$new_memory" || return 1
        fi

        if [[ -n "$new_cpu" ]]; then
            compose_edit_cpu "$site_name" "$new_cpu" || return 1
        fi
    fi

    # Report changes
    if [[ -n "$new_php_version" ]]; then
        log_info "PHP version: $current_php_version -> php$new_php_version"
        has_changes=true
    fi
    if [[ -n "$new_port" ]]; then
        log_info "Port: $current_port -> $new_port"
        has_changes=true
    fi
    if [[ -n "$new_memory" ]]; then
        if site_has_nginx "$site_name"; then
            local nginx_mem
            nginx_mem=$(echo "$new_memory" | sed 's/^\([0-9]*\).*/\1/')
            local nginx_mem_unit=$(echo "$new_memory" | sed 's/^[0-9]*//I')
            if [[ "$nginx_mem_unit" == "G" || "$nginx_mem_unit" == "g" ]]; then
                nginx_mem=$((nginx_mem / 2))
                [[ $nginx_mem -lt 128 ]] && nginx_mem=128
                nginx_mem="${nginx_mem}m"
            elif [[ "$nginx_mem_unit" == "M" || "$nginx_mem_unit" == "m" ]]; then
                nginx_mem=$((nginx_mem / 2))
                [[ $nginx_mem -lt 128 ]] && nginx_mem=128
                nginx_mem="${nginx_mem}m"
            else
                nginx_mem="128m"
            fi
            log_info "Memory: PHP-FPM ${new_memory}, nginx ${nginx_mem}"
        else
            log_info "Memory: Apache/PHP-FPM ${new_memory}"
        fi
        has_changes=true
    fi
    if [[ -n "$new_cpu" ]]; then
        if site_has_nginx "$site_name"; then
            local nginx_cpu
            nginx_cpu=$(echo "$new_cpu" | awk '{print $1/2}')
            [[ $(echo "$nginx_cpu < 0.25" | bc -l 2>/dev/null || echo 0) -eq 1 ]] && nginx_cpu=0.25
            log_info "CPU: PHP-FPM ${new_cpu}, nginx ${nginx_cpu}"
        else
            log_info "CPU: Apache/PHP-FPM ${new_cpu}"
        fi
        has_changes=true
    fi

    if ! $has_changes; then
        echo "Current configuration for '$site_name':"
        [[ -n "$current_php_version" ]] && echo "  PHP version: $current_php_version"
        [[ -n "$current_port" ]] && echo "  Port: $current_port (http://$HOST_IP:$current_port)"
        echo ""
        echo "Usage: ./matrix edit $site_name [--php-version=X.X] [--port=XXXX]"
        return 0
    fi

    # Restart the site if it was running
    if compose_or_container_running "wp_$site_name"; then
        log_info "Restarting site '$site_name' to apply changes..."
        if [[ -n "$new_php_version" && "$(get_site_stack "$site_name")" == "apache" ]]; then
            matrix_site_build_if_apache "$site_name" || return 1
        fi
        matrix_site_restart "$site_name"
        log_success "Site restarted"
    fi

    log_success "Site '$site_name' updated"
    log_activity "EDIT" "$site_name" "Updated configuration"
}

# Rename an existing site to a new name.
rename_site() {
    local old_name=""
    local new_name=""
    local delete_old=false

    while [[ $# -gt 0 ]]; do
        case "$1" in
            --delete-old)
                delete_old=true
                shift
                ;;
            -*)
                log_error "Unknown option: $1"
                echo "Usage: ./matrix rename <old-name> <new-name> [--delete-old]"
                return 1
                ;;
            *)
                if [[ -z "$old_name" ]]; then
                    old_name="$1"
                elif [[ -z "$new_name" ]]; then
                    new_name="$1"
                fi
                shift
                ;;
        esac
    done

    if [[ -z "$old_name" || -z "$new_name" ]]; then
        log_error "Usage: ./matrix rename <old-name> <new-name> [--delete-old]"
        return 1
    fi

    validate_site_name "$old_name" || return 1
    validate_site_name "$new_name" || return 1

    if ! site_exists "$old_name"; then
        log_error "Site '$old_name' not found"
        return 1
    fi

    if [[ "$old_name" == "$new_name" ]]; then
        log_error "Old and new names are identical"
        return 1
    fi

    if site_exists "$new_name"; then
        log_error "Site '$new_name' already exists"
        return 1
    fi

    log_info "Renaming site '$old_name' to '$new_name'..."

    local original_dir="$PROJECT_ROOT/wp_$old_name"
    local new_dir="$PROJECT_ROOT/wp_$new_name"

    # Actual source DB name (wp-config may point elsewhere after earlier renames)
    local src_db_name=""
    if [[ -f "$original_dir/wp-config.php" ]]; then
        src_db_name=$(grep "define.*DB_NAME" "$original_dir/wp-config.php" | head -1 | cut -d"'" -f4)
    fi
    src_db_name="${src_db_name:-${old_name}_db}"

    # Stop the site if running
    matrix_site_stop "$old_name" || true

    # Backup the database before rename (safety net)
    log_info "Backing up database before rename..."
    "$PROJECT_ROOT/scripts/backup.sh" "$old_name" >/dev/null 2>&1 || log_warning "Backup failed (non-fatal)"

    # Rename the site directory
    if [[ -d "$original_dir" ]]; then
        mv "$original_dir" "$new_dir" || {
            log_error "Failed to rename directory"
            return 1
        }
    fi

    # Rename the logs directory
    if [[ -d "$PROJECT_ROOT/logs/wp_$old_name" ]]; then
        mv "$PROJECT_ROOT/logs/wp_$old_name" "$PROJECT_ROOT/logs/wp_$new_name" 2>/dev/null || true
    fi

    # Rename the nginx config file and update its fastcgi_pass upstream
    local old_nginx_conf="$PROJECT_ROOT/config/nginx/$old_name.conf"
    local new_nginx_conf="$PROJECT_ROOT/config/nginx/$new_name.conf"
    if [[ -f "$old_nginx_conf" ]]; then
        mv "$old_nginx_conf" "$new_nginx_conf" || log_warning "Could not rename nginx config"
    fi
    if [[ -f "$new_nginx_conf" ]]; then
        sed -i.bak "s/fastcgi_pass wp_${old_name}:9000;/fastcgi_pass wp_${new_name}:9000;/" "$new_nginx_conf"
        rm -f "$new_nginx_conf.bak"
    fi

    # Capture compose settings before removing the old services
    local port=""
    local php_version=""
    local stack=""
    local table_prefix=""
    if site_in_compose "$old_name"; then
        port=$(get_site_port_from_compose "$old_name")
        php_version=$(get_site_php_version_from_compose "$old_name")
        stack=$(get_site_stack "$old_name")
        # Preserve custom WORDPRESS_TABLE_PREFIX if set
        table_prefix=$(grep -A 20 "wp_${old_name}:" "$COMPOSE_FILE" | grep "WORDPRESS_TABLE_PREFIX:" | head -1 | sed 's/.*WORDPRESS_TABLE_PREFIX:\s*//' | tr -d '"' || true)

        compose_remove_site "$old_name" || log_warning "compose_remove_site failed"

        local nginx_conf_path="$PROJECT_ROOT/config/nginx/$new_name.conf"
        if [[ "$stack" == "apache" ]]; then
            nginx_conf_path=""
        fi
        compose_add_site "$new_name" "$php_version" "$port" "$nginx_conf_path" "$stack" "$(get_site_type "$new_name")" || {
            log_error "Failed to add renamed site to docker-compose"
            return 1
        }
        # Preserve custom WORDPRESS_TABLE_PREFIX if set
        if [[ -n "$table_prefix" ]]; then
            sed -i.bak "s/WORDPRESS_DEBUG: \${WP_DEBUG:-true}/WORDPRESS_DEBUG: \${WP_DEBUG:-true}\n      WORDPRESS_TABLE_PREFIX: ${table_prefix}/" "$COMPOSE_FILE"
            rm -f "$COMPOSE_FILE.bak"
        fi
    fi

    # Rename the database (if the DB container is running; never for no-db types)
    if site_type_uses_db "$(get_site_type "$new_name")" && compose_or_container_running "wp_db"; then
        log_info "Renaming database ${src_db_name} -> ${new_name}_db..."
        $CONTAINER_RUNTIME exec -e MYSQL_PWD="${MYSQL_ROOT_PASSWORD:-root}" wp_db mysql -u root -e "CREATE DATABASE IF NOT EXISTS \`${new_name}_db\`;" 2>/dev/null || true
        local db_user="${MYSQL_USER:-wp_user}"
        $CONTAINER_RUNTIME exec -e MYSQL_PWD="${MYSQL_ROOT_PASSWORD:-root}" wp_db mysql -u root -e "GRANT ALL PRIVILEGES ON \`${new_name}_db\`.* TO '${db_user}'@'%'; FLUSH PRIVILEGES;" 2>/dev/null || true
        $CONTAINER_RUNTIME exec -e MYSQL_PWD="${MYSQL_ROOT_PASSWORD:-root}" wp_db sh -c "mysqldump --no-tablespaces -u root \`${src_db_name}\` | mysql -u root \`${new_name}_db\`" 2>/dev/null || log_warning "Database copy failed"
        if [[ "$src_db_name" != "${new_name}_db" ]]; then
            $CONTAINER_RUNTIME exec -e MYSQL_PWD="${MYSQL_ROOT_PASSWORD:-root}" wp_db mysql -u root -e "DROP DATABASE IF EXISTS \`${src_db_name}\`;" 2>/dev/null || true
        fi
    fi

    # Update wp-config.php DB name and table prefix
    if [[ -f "$new_dir/wp-config.php" ]]; then
        sed -i.bak "s/define( *['\"]DB_NAME['\"].*/define( 'DB_NAME', '${new_name}_db' );/" "$new_dir/wp-config.php"
        rm -f "$new_dir/wp-config.php.bak"
        # Preserve the original table prefix from the source wp-config
        if [[ -f "$original_dir/wp-config.php" ]]; then
            local old_prefix
            old_prefix=$(grep '\$table_prefix' "$original_dir/wp-config.php" | head -1 | grep -o "'[^']*'" | head -1 | tr -d "'")
            local new_prefix
            new_prefix=$(grep '\$table_prefix' "$new_dir/wp-config.php" | head -1 | grep -o "'[^']*'" | head -1 | tr -d "'")
            if [[ -n "$old_prefix" && "$old_prefix" != "$new_prefix" ]]; then
                sed -i.bak "s/\$table_prefix = '$new_prefix'/\$table_prefix = '$old_prefix'/" "$new_dir/wp-config.php"
                rm -f "$new_dir/wp-config.php.bak"
            fi
        fi
    fi

    # Non-wp: repoint the moved config at the new database name, or the
    # renamed site keeps serving from the OLD database (same shared-DB bug
    # as clone/import — see repoint_clone_env).
    if [[ "$(get_site_type "$new_name")" != "wp" ]]; then
        repoint_clone_env "$new_dir" "$old_name" "$new_name"
    fi

    # Update .env site-specific port variable
    if [[ -f "$PROJECT_ROOT/.env" ]]; then
        local old_env_var
        old_env_var=$(echo "$old_name" | tr '[:lower:]' '[:upper:]' | tr '-' '_')
        local new_env_var
        new_env_var=$(echo "$new_name" | tr '[:lower:]' '[:upper:]' | tr '-' '_')
        local port_value
        port_value=$(grep "^${old_env_var}_PORT=" "$PROJECT_ROOT/.env" | cut -d'=' -f2 || true)
        if [[ -n "$port_value" ]]; then
            grep -v "^${old_env_var}_PORT=" "$PROJECT_ROOT/.env" > "$PROJECT_ROOT/.env.tmp" || true
            echo "# Site: $new_name" >> "$PROJECT_ROOT/.env.tmp"
            echo "${new_env_var}_PORT=$port_value" >> "$PROJECT_ROOT/.env.tmp"
            mv "$PROJECT_ROOT/.env.tmp" "$PROJECT_ROOT/.env"
        fi
    fi

    # Optionally delete old site files
    if $delete_old; then
        log_info "Deleting old site data (--delete-old)..."
        remove_site_dir "$PROJECT_ROOT/wp_$old_name" "$old_name" || return 1
        rm -rf "$PROJECT_ROOT/logs/wp_$old_name" 2>/dev/null || true
        rm -f "$PROJECT_ROOT/config/nginx/$old_name.conf" 2>/dev/null || true
    fi

    # Start the renamed site
    log_info "Starting renamed site '$new_name'..."
    if [[ "$stack" == "apache" ]]; then
        matrix_site_build_if_apache "$new_name" || return 1
    fi
    matrix_site_up "$new_name"

    log_success "Site renamed from '$old_name' to '$new_name'"
    log_activity "RENAME" "$old_name" "Renamed to $new_name"
    show_urls "$new_name"
}

# Run a tool container with compose --profile, falling back to direct run for podman
run_tool_container() {
    local service="${1:-}"

    if [[ -z "$service" ]]; then
        log_error "Usage: ./matrix check <site> [path] or ./matrix run-tool <tool-name>"
        return 1
    fi
    shift
    if $DOCKER_COMPOSE --profile tools run --rm "$service" "$@" 2>/dev/null; then
        return 0
    fi
    local db_network
    db_network=$(get_db_network)
    local network_args=()
    if [[ -n "$db_network" ]]; then
        network_args=(--network "$db_network")
    fi
    case "$service" in
        phpcs)
            $CONTAINER_RUNTIME run --rm -v "$PROJECT_ROOT":/workspace:ro -w /workspace "${network_args[@]}" \
                wpengine/phpcs:latest "$@"
            ;;
        phpstan)
            $CONTAINER_RUNTIME run --rm -v "$PROJECT_ROOT":/project:ro -w /project "${network_args[@]}" \
                ghcr.io/phpstan/phpstan:latest "$@"
            ;;
        wp-cli)
            $CONTAINER_RUNTIME run --rm -v "$PROJECT_ROOT":/var/www/html:rw -w /var/www/html "${network_args[@]}" \
                wordpress:cli "$@"
            ;;
        *)
            log_error "Unknown tool service: $service"
            return 1
            ;;
    esac
}

# Code quality checks
run_checks() {
    local site_name="${1:-}"
    local specific_path="${2:-}"
    local target_paths=""
    
    if [[ -n "$site_name" ]]; then
        validate_site_name "$site_name" || return 1
        local site_dir="wp_${site_name}"
        if [[ ! -d "$site_dir" ]]; then
            log_error "Site '$site_name' not found (directory: $site_dir)"
            return 1
        fi
        # phpcs targets wp-content/{themes,plugins}; other stacks have none.
        require_site_type "$site_name" wp || return 1
        
        if [[ -n "$specific_path" ]]; then
            target_paths="./${site_dir}/${specific_path}"
            log_info "Running code quality checks on: $site_name/$specific_path"
        else
            target_paths="./${site_dir}/wp-content/themes/ ./${site_dir}/wp-content/plugins/"
            log_info "Running code quality checks on site: $site_name"
            log_info "Excluding default WordPress themes, vendor, and common plugins"
        fi
    else
        target_paths="./wp_*/wp-content/themes/ ./wp_*/wp-content/plugins/"
        log_info "Running code quality checks on all sites..."
        log_info "Excluding default WordPress themes, vendor, and common plugins"
    fi
    
    # Check if code quality containers exist in $DOCKER_COMPOSE
    if ! grep -q "phpcs" "$COMPOSE_FILE" 2>/dev/null; then
        log_warning "Code quality tools not configured"
        return
    fi
    
    # Build exclude patterns for default/third-party themes and plugins
    local exclude_patterns=""
    exclude_patterns="$exclude_patterns --ignore=*/vendor/*"
    exclude_patterns="$exclude_patterns --ignore=*/node_modules/*"
    exclude_patterns="$exclude_patterns --ignore=*/.git/*"
    exclude_patterns="$exclude_patterns --ignore=*/tests/*"
    exclude_patterns="$exclude_patterns --ignore=*/twentytwenty*/*"
    exclude_patterns="$exclude_patterns --ignore=*/twenty*/*"
    exclude_patterns="$exclude_patterns --ignore=*/index.php"
    exclude_patterns="$exclude_patterns --ignore=*/akismet/*"
    exclude_patterns="$exclude_patterns --ignore=*/hello.php"
    exclude_patterns="$exclude_patterns --ignore=*/advanced-custom-fields*/*"
    exclude_patterns="$exclude_patterns --ignore=*/elementor/*"
    exclude_patterns="$exclude_patterns --ignore=*/wordpress-seo/*"
    exclude_patterns="$exclude_patterns --ignore=*/redirection/*"
    exclude_patterns="$exclude_patterns --ignore=*/litespeed-cache/*"
    exclude_patterns="$exclude_patterns --ignore=*/better-search-replace/*"
    exclude_patterns="$exclude_patterns --ignore=*/defender*/*"
    exclude_patterns="$exclude_patterns --ignore=*/sg-security/*"
    exclude_patterns="$exclude_patterns --ignore=*/duplicate-page/*"
    exclude_patterns="$exclude_patterns --ignore=*/really-simple-ssl/*"
    exclude_patterns="$exclude_patterns --ignore=*/classic-elementor*/*"
    exclude_patterns="$exclude_patterns --ignore=*/revslider/*"
    exclude_patterns="$exclude_patterns --ignore=*/export-posts*/*"
    exclude_patterns="$exclude_patterns --ignore=*/csv-taxonomy*/*"
    exclude_patterns="$exclude_patterns --ignore=*/wp-file-manager/*"
    
    # Run PHP CodeSniffer
    log_info "Running PHP CodeSniffer..."
    run_tool_container phpcs \
        -d memory_limit=512M \
        --standard=WordPress \
        --extensions=php \
        $exclude_patterns \
        $target_paths 2>/dev/null || \
    log_warning "PHP CodeSniffer check completed with issues"
    
    # Run PHPStan (only on custom code to avoid timeout)
    if [[ -n "$specific_path" ]]; then
        log_info "Running PHPStan..."
        run_tool_container phpstan analyse \
            --memory-limit=512M \
            $target_paths --level=9 2>/dev/null || \
        log_warning "PHPStan check completed with issues"
    else
        log_info "Skipping PHPStan (use specific path to run PHPStan: ./matrix check <site> <path>)"
    fi
    
    log_info "Code quality checks completed"
}

# Access shell
access_shell() {
    local service="${1:-}"

    if [[ -z "$service" ]]; then
        log_error "Usage: ./matrix shell <service>"
        log_info "Available: wp, db, nginx"
        return 1
    fi

    local exec_flags=("-it")
    if [[ ! -t 0 ]]; then
        exec_flags=("-i")
    fi

    case "$service" in
        "wp"|"wordpress")
            # Get running WordPress containers (exclude db, redis, and other services)
            local running_containers=($($CONTAINER_RUNTIME ps --format "{{.Names}}" 2>/dev/null | grep "^wp_" | grep -vE "wp_db|wp_redis|wp_phpmyadmin|wp_phpcs|wp_phpstan|wp_cli" || true))
            if [[ ${#running_containers[@]} -eq 0 ]]; then
                log_error "No WordPress containers running"
                return 1
            fi
            
            # Use first running WordPress container
            local container_name="${running_containers[0]}"
            echo "Accessing container: $container_name"
            $CONTAINER_RUNTIME exec "${exec_flags[@]}" "$container_name" bash || {
                log_error "Failed to access WordPress container"
                return 1
            }
            ;;
        "db"|"database")
            $CONTAINER_RUNTIME exec "${exec_flags[@]}" -e MYSQL_PWD="${MYSQL_ROOT_PASSWORD:-root}" wp_db mysql -u root
            ;;
        "nginx"|"proxy")
            local nginx_containers=($($CONTAINER_RUNTIME ps --format "{{.Names}}" 2>/dev/null | grep "^nginx_" || true))
            if [[ ${#nginx_containers[@]} -eq 0 ]]; then
                log_error "No nginx containers running"
                return 1
            fi
            
            # Use first running nginx container
            local container_name="${nginx_containers[0]}"
            echo "Accessing container: $container_name"
            $CONTAINER_RUNTIME exec "${exec_flags[@]}" "$container_name" sh || {
                log_error "Failed to access nginx container"
                return 1
            }
            ;;
        *)
            log_error "Unknown service: $service"
            echo "Available: wp, db, nginx"
            return 1
            ;;
    esac
}

show_info_json() {
    local site_name="${1:-}"

    if [[ -z "$site_name" ]]; then
        error_json "INVALID_NAME" "Site name is required"
    fi
    if ! validate_site_name "$site_name" >/dev/null 2>&1; then
        error_json "INVALID_NAME" "Invalid site name"
    fi

    if ! site_exists "$site_name"; then
        error_json "SITE_NOT_FOUND" "Site '$site_name' does not exist"
    fi

    check_docker_json

    local status="stopped"
    if compose_or_container_running "wp_$site_name"; then
        status="running"
    fi

    local port=""
    port=$(get_site_port "$site_name")

    local php_version=""
    php_version=$(get_site_php_version_from_compose "$site_name")

    local stack
    stack=$(get_site_stack "$site_name")

    local container_id=""
    if [[ "$status" == "running" ]]; then
        container_id=$($CONTAINER_RUNTIME ps -q -f "name=^/wp_${site_name}\$" 2>/dev/null | head -1)
        [[ -z "$container_id" ]] && container_id=$($CONTAINER_RUNTIME ps -q -f name="wp_$site_name" 2>/dev/null | head -1)
    fi

    local local_url="null"
    if [[ -n "$port" ]]; then
        local_url="\"http://$HOST_IP:$port\""
    fi

    local db_name="${site_name}_db"

    local db_size="null"
    if [[ "$status" == "running" ]]; then
        db_size=$($CONTAINER_RUNTIME exec -e MYSQL_PWD="${MYSQL_ROOT_PASSWORD:-root}" wp_db mysql -u root -sN -e "SELECT ROUND(SUM(data_length + index_length) / 1024 / 1024, 2) FROM information_schema.tables WHERE table_schema='${site_name}_db'" 2>/dev/null || true)
        if [[ -n "$db_size" && "$db_size" != "NULL" ]]; then
            db_size="$db_size"
        else
            db_size="null"
        fi
    fi

    local disk_usage="null"
    if [[ -d "$PROJECT_ROOT/wp_$site_name" ]]; then
        disk_usage="\"$(du -sh "$PROJECT_ROOT/wp_$site_name" 2>/dev/null | cut -f1)\""
    fi

    local nginx_config="null"
    if [[ "$stack" == "nginx" ]]; then
        nginx_config="\"config/nginx/$site_name.conf\""
    fi

    local wp_version="null"
    if [[ -f "$PROJECT_ROOT/wp_$site_name/wp-includes/version.php" ]]; then
        wp_version=$(grep "wp_version =" "$PROJECT_ROOT/wp_$site_name/wp-includes/version.php" 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' || true)
        if [[ -n "$wp_version" ]]; then
            wp_version="\"$wp_version\""
        else
            wp_version="null"
        fi
    fi

    local php_version_json="null"
    if [[ -n "$php_version" ]]; then
        php_version_json="\"$php_version\""
    fi

    local container_id_json="null"
    if [[ -n "$container_id" ]]; then
        container_id_json="\"$container_id\""
    fi

    local multisite_json="false"
    local multisite_mode_json="null"
    if site_is_multisite "$site_name"; then
        multisite_json="true"
        local ms_mode
        ms_mode=$(site_multisite_mode "$site_name")
        [[ -n "$ms_mode" ]] && multisite_mode_json="\"$ms_mode\""
    fi

    output_json "{\"success\":true,\"site\":{\"name\":\"$site_name\",\"status\":\"$status\",\"stack\":\"$stack\",\"port\":${port:-null},\"phpVersion\":$php_version_json,\"containerId\":$container_id_json,\"localUrl\":$local_url,\"dbName\":\"$db_name\",\"dbSize\":$db_size,\"diskUsage\":$disk_usage,\"nginxConfigPath\":$nginx_config,\"wordpressVersion\":$wp_version,\"multisite\":$multisite_json,\"multisite_mode\":$multisite_mode_json}}"
}

# Show URLs
show_urls() {
    local site_name="${1:-}"

    if [[ -n "$site_name" ]]; then
        validate_site_name "$site_name" || return 1
        if site_exists "$site_name"; then
            local port
            port=$(get_site_port "$site_name")
            if [[ -z "$port" ]]; then
                echo "Site '$site_name' exists but has no exposed port"
                return 1
            fi
            echo "Access: http://$HOST_IP:$port"
            echo "Database: http://$HOST_IP:8200"
        else
            log_error "Site '$site_name' not found"
            return 1
        fi
    else
        echo "Services:"
        echo "WordPress sites: http://$HOST_IP:[assigned_port]"
        echo "Database admin: http://$HOST_IP:8200"
        echo "Email viewer: http://$HOST_IP:8025"
    fi
}

rest_site() {
    local site_name="${1:-}"
    validate_site_name "$site_name" || return 1

    if ! site_exists "$site_name"; then
        log_error "Site '$site_name' not found"
        return 1
    fi

    local port=""
    port=$(get_site_port "$site_name")
    if [[ -z "$port" ]]; then
        log_error "No URL available for site '$site_name'"
        return 1
    fi

    local rest_url="http://$HOST_IP:$port/wp-json/"
    if command -v python3 >/dev/null 2>&1; then
        curl -fsSL "$rest_url" | python3 -m json.tool
    else
        curl -fsSL "$rest_url"
    fi
}

# Setup environment
setup_env() {
    log_info "Setting up environment..."
    
    # Create .env if not exists
    if [[ ! -f "$PROJECT_ROOT/.env" ]]; then
        local gen_pass
        gen_pass=$(openssl rand -hex 16 2>/dev/null || head -c 32 /dev/urandom | base64 | tr -dc 'a-zA-Z0-9' | head -c 24)
        local gen_root_pass
        gen_root_pass=$(openssl rand -hex 16 2>/dev/null || head -c 32 /dev/urandom | base64 | tr -dc 'a-zA-Z0-9' | head -c 24)
        local gen_redis_pass
        gen_redis_pass=$(openssl rand -hex 16 2>/dev/null || head -c 32 /dev/urandom | base64 | tr -dc 'a-zA-Z0-9' | head -c 24)
        cat > "$PROJECT_ROOT/.env" << EOF
# SiteMatrix environment — multi-PHP stack credentials and configs
DOMAIN_SUFFIX=${HOST_IP}.nip.io
MYSQL_USER=wp_user
MYSQL_PASSWORD=${gen_pass}
MYSQL_ROOT_PASSWORD=${gen_root_pass}
REDIS_PASSWORD=${gen_redis_pass}
WP_DEBUG=true
EOF
        log_success "Created .env file with generated credentials"
        chmod 600 "$PROJECT_ROOT/.env"
    fi
    
    # Create simplified $DOCKER_COMPOSE.yml if not exists
    if [[ ! -f "$PROJECT_ROOT/$DOCKER_COMPOSE.yml" ]]; then
        cat > "$PROJECT_ROOT/$DOCKER_COMPOSE.yml" << EOF
networks:
  wp-net:
    driver: bridge

services:
  # Database
  db:
    image: mysql:8.0
    container_name: wp_db
    restart: unless-stopped
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: \${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: wp_main
      MYSQL_USER: \${MYSQL_USER}
      MYSQL_PASSWORD: \${MYSQL_PASSWORD}
    volumes:
      - wp_db_data:/var/lib/mysql
    networks:
      - wp-net

  # Cache
  redis:
    image: redis:alpine
    container_name: wp_redis
    restart: unless-stopped
    networks:
      - wp-net

volumes:
  wp_db_data:
EOF
        log_success "Created $DOCKER_COMPOSE.yml"
    fi
    
    # Create config directories
    mkdir -p "$PROJECT_ROOT/config/nginx"
    
    # Create default nginx config
    if [[ ! -f "$PROJECT_ROOT/config/nginx/default.conf" ]]; then
        cat > "$PROJECT_ROOT/config/nginx/default.conf" << 'EOF'
server {
    listen 80 default_server;
    server_name _;
    root /var/www/html;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass localhost:9000;  # Default to localhost for single container use
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
EOF
        log_success "Created default nginx configuration"
    fi
    
    # Ensure the wp_ directory exists for the main project (if this is the root)
    if [[ ! -d "$PROJECT_ROOT/wp_" ]]; then
        mkdir -p "$PROJECT_ROOT/wp_"
        # This is for the main project directory if needed
    fi

    log_success "Setup complete! Run './matrix start' to begin"
}

# Install complete WordPress environment with one command
install_env() {
    local site_name="${1:-wordpress}"

    log_info "Installing complete environment..."

    # Make sure we have the simple compose file
    if [[ ! -f "$PROJECT_ROOT/docker-compose.simple.yml" ]]; then
        log_error "docker-compose.simple.yml not found"
        return 1
    fi

    # Always create or overwrite the compose file with Traefik-free version
    cat > "$PROJECT_ROOT/docker-compose.yml" << 'EOF'
networks:
  wp-net:
    driver: bridge

services:
  # Database
  db:
    image: mysql:8.0
    container_name: wp_db
    restart: unless-stopped
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: wp_main
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - wp_db_data:/var/lib/mysql
    networks:
      - wp-net
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      timeout: 20s
      retries: 10

  # Cache
  redis:
    image: redis:alpine
    container_name: wp_redis
    restart: unless-stopped
    networks:
      - wp-net
    command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru

  # Database admin panel
  phpmyadmin:
    image: phpmyadmin:latest
    container_name: wp_phpmyadmin
    restart: unless-stopped
    ports:
      - "8200:80"  # Direct access to phpMyAdmin
    environment:
      PMA_HOST: db
      PMA_USER: ${MYSQL_USER:-wp_user}
      PMA_PASSWORD: ${MYSQL_PASSWORD:-wp_password}
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-root}
    networks:
      - wp-net
    depends_on:
      - db

volumes:
  wp_db_data:
EOF
    log_success "Created Traefik-free docker-compose.yml"

    # Run setup if .env doesn't exist
    if [[ ! -f "$PROJECT_ROOT/.env" ]]; then
        setup_env
    fi

    # Start the base services (db, redis)
    log_info "Starting base services..."
    $DOCKER_COMPOSE up -d db redis

    # Wait for database to be ready
    log_info "Waiting for database to be ready..."
    local max_attempts=30
    local attempt=1
    while [[ $attempt -le $max_attempts ]]; do
        if $DOCKER_COMPOSE exec -T -e MYSQL_PWD="${MYSQL_PASSWORD:-wp_password}" db mysqladmin ping -h localhost -u "${MYSQL_USER:-wp_user}" --silent 2>/dev/null; then
            log_success "Database is ready!"
            break
        else
            log_info "Waiting for database... ($attempt/$max_attempts)"
            sleep 5
            ((attempt++))
        fi
    done

    if [[ $attempt -gt $max_attempts ]]; then
        log_error "Database failed to start after $max_attempts attempts"
        return 1
    fi

    # Check if site already exists
    if ! site_exists "$site_name"; then
        log_info "Creating WordPress site: $site_name"
        create_site "$site_name"
    else
        log_info "Site '$site_name' already exists"
    fi

    # Start all services
    log_info "Starting all services..."
    start_env

    log_success "Environment installed successfully!"
    echo ""
    echo "Your site is available at:"
    echo "  http://$HOST_IP:[port]"
    echo ""
    log_success "Installation complete! 🚀"
}

# Database import function
import_db() {
    local site_name="${1:-}"
    local dump_file="${2:-}"

    if [[ -z "$site_name" || -z "$dump_file" ]]; then
        log_error "Usage: ./matrix import-db <site-name> <dump-file>"
        return 1
    fi
    validate_site_name "$site_name" || return 1

    if [[ ! -f "$dump_file" ]]; then
        log_error "Dump file not found: $dump_file"
        return 1
    fi

    if ! site_exists "$site_name"; then
        log_error "Site '$site_name' not found"
        return 1
    fi

    local db_name="${site_name}_db"
    log_info "Importing database for '$site_name' ($db_name)..."

    # Decompress if needed
    local sql_file="$dump_file"
    local tmp_file=""
    if [[ "$dump_file" == *.zip ]]; then
        tmp_file="$(mktemp /tmp/import_db_XXXXXX)"
        unzip -p "$dump_file" > "$tmp_file" || { log_error "Failed to unzip: $dump_file"; rm -f "$tmp_file"; return 1; }
        sql_file="$tmp_file"
    elif [[ "$dump_file" == *.gz ]]; then
        tmp_file="$(mktemp /tmp/import_db_XXXXXX)"
        gunzip -c "$dump_file" > "$tmp_file" || { log_error "Failed to gunzip: $dump_file"; rm -f "$tmp_file"; return 1; }
        sql_file="$tmp_file"
    fi

    # Allow stored functions/triggers without SUPER privilege (avoids ERROR 1419
    # when binary logging is enabled). Set as GLOBAL with root so it applies to
    # the import session below; SESSION would not carry over to a new connection.
    $CONTAINER_RUNTIME exec -e MYSQL_PWD="${MYSQL_ROOT_PASSWORD:-root}" wp_db mysql -u root \
        -e "SET GLOBAL log_bin_trust_function_creators = 1;" 2>/dev/null || true

    # Import the SQL dump
    local import_rc=0
    $CONTAINER_RUNTIME exec -i -e MYSQL_PWD="${MYSQL_PASSWORD:-wp_password}" wp_db mysql -u "${MYSQL_USER:-wp_user}" "$db_name" < "$sql_file" || import_rc=$?

    if [[ -n "$tmp_file" ]]; then
        rm -f "$tmp_file"
    fi

    if [[ $import_rc -eq 0 ]]; then
        log_success "Database imported successfully for '$site_name'"
    else
        log_error "Failed to import database for '$site_name'"
        return 1
    fi
}

# Database export function
export_db() {
    local site_name="${1:-}"
    local output_file="${2:-}"

    if [[ -z "$site_name" ]]; then
        log_error "Usage: ./matrix export-db <site-name> [output-file]"
        return 1
    fi
    validate_site_name "$site_name" || return 1

    if ! site_exists "$site_name"; then
        log_error "Site '$site_name' not found"
        return 1
    fi

    local db_name="${site_name}_db"

    if [[ -z "$output_file" ]]; then
        output_file="${site_name}_$(date +%Y%m%d_%H%M%S).sql"
        log_info "Exporting database for '$site_name' to $output_file..."
    else
        log_info "Exporting database for '$site_name' to $output_file..."
    fi

    # Export the database
    if $CONTAINER_RUNTIME exec -e MYSQL_PWD="${MYSQL_PASSWORD:-wp_password}" wp_db mysqldump --no-tablespaces -u "${MYSQL_USER:-wp_user}" "$db_name" > "$output_file"; then
        log_success "Database exported successfully to '$output_file'"
        echo "File size: $(du -h "$output_file" | cut -f1)"
    else
        local dump_rc=$?
        rm -f "$output_file"
        log_error "Failed to export database for '$site_name' (exit $dump_rc)"
        return 1
    fi
}

# Clean up
clean_env() {
    log_warning "This will remove unused Docker resources"
    local confirm=""
    read -r -p "Continue? [y/N]: " confirm || confirm=""

    if [[ "$confirm" =~ ^[Yy]$ ]]; then
        $CONTAINER_RUNTIME system prune -f 2>/dev/null || true
        $CONTAINER_RUNTIME volume prune -f 2>/dev/null || true
        log_success "Cleanup complete"
    fi
}

# Configure Xdebug for a site
configure_xdebug() {
    local site_name="${1:-}"

    if [[ -z "$site_name" ]]; then
        log_error "Usage: ./matrix xdebug <site-name>"
        return 1
    fi
    validate_site_name "$site_name" || return 1

    if ! site_exists "$site_name"; then
        log_error "Site '$site_name' not found"
        return 1
    fi

    local site_dir="$PROJECT_ROOT/wp_$site_name"
    log_info "Configuring Xdebug for site '$site_name'..."

    local user_ini="$site_dir/.user.ini"

    # Check if Xdebug config already exists
    if [[ -f "$user_ini" ]] && grep -q "xdebug.mode" "$user_ini" 2>/dev/null; then
        log_warning "Xdebug already configured for '$site_name'"
        echo ""
        echo "Xdebug settings:"
        grep "xdebug\\." "$user_ini" || true
        return 0
    fi

    # Xdebug is configured with PHP INI directives, not wp-config.php PHP code.
    cat >> "$user_ini" << 'EOF'
xdebug.mode = develop,debug;
xdebug.client_host = host.docker.internal;
xdebug.start_with_request = yes;
xdebug.idekey = "VSCODE";
EOF

    log_success "Xdebug enabled for '$site_name' (always on)"
    echo ""
    echo "For VS Code:"
    echo "1. Install PHP Debug extension"
    echo "2. Add this to .vscode/launch.json:"
    echo '   { "name": "Listen for Xdebug", "type": "php", "request": "launch", "pathMappings": { "/var/www/html": "${workspaceFolder}" }, "port": 9003 }'
    echo ""
    echo "For PHPStorm:"
    echo "1. Settings > PHP > Servers: Add mapping /var/www/html -> $site_dir"
    echo "2. Use browser extension or add ?XDEBUG_SESSION_START to URL"
}

# Scaffold theme or plugin
scaffold_project() {
    local type="${1:-}"
    local name="${2:-}"

    if [[ -z "$type" || -z "$name" ]]; then
        log_error "Usage: ./matrix scaffold <type> <name>"
        echo ""
        echo "Types:"
        echo "  theme <name>  - Create a new theme"
        echo "  plugin <name>  - Create a new plugin"
        echo "  child <name>  - Create a child theme"
        return 1
    fi

    case "$type" in
        "theme")
            scaffold_theme "$name"
            ;;
        "plugin")
            scaffold_plugin "$name"
            ;;
        "child")
            scaffold_child_theme "$name"
            ;;
        *)
            log_error "Unknown scaffold type: $type"
            echo "Valid types: theme, plugin, child"
            return 1
            ;;
    esac
}

scaffold_theme() {
    local name="${1:-}"

    if [[ -z "$name" ]]; then
        log_error "Usage: ./matrix scaffold theme <name>"
        return 1
    fi
    if [[ ! "$name" =~ ^[a-zA-Z][a-zA-Z0-9_-]*$ ]]; then
        log_error "Invalid theme name '$name'. Use a letter first, then letters, numbers, hyphens, or underscores."
        return 1
    fi

    local themes_dir="$PROJECT_ROOT/wp_content/themes"
    local theme_dir="$themes_dir/$name"

    if [[ -d "$theme_dir" ]]; then
        log_error "Theme directory already exists: $theme_dir"
        return 1
    fi

    log_info "Creating theme '$name'..."

    mkdir -p "$theme_dir"

    # Create style.css
    cat > "$theme_dir/style.css" << EOF
/*
Theme Name: $name
Theme URI: http://example.com/$name
Description: Custom theme created with SiteMatrix
Author: Developer
Version: 1.0.0
Text Domain: $name
*/

EOF

    # Create index.php
    cat > "$theme_dir/index.php" << 'EOF'
<?php
/**
 * Theme functions and definitions
 */

defined('ABSPATH') || exit;

if (!defined('THEME_VERSION')) {
    define('THEME_VERSION', '1.0.0');
}

// Theme setup
function theme_setup() {
    add_theme_support('title-tag');
    add_theme_support('post-thumbnails');
    add_theme_support('automatic-feed-links');

    register_nav_menus(array(
        'primary' => __('Primary Menu', 'THEME_TEXT_DOMAIN'),
    ));
}
add_action('after_setup_theme', 'theme_setup');

// Enqueue scripts and styles
function theme_scripts() {
    wp_enqueue_style('theme-style', get_stylesheet_uri(), array(), THEME_VERSION);
    wp_enqueue_script('theme-script', get_template_directory_uri() . '/assets/js/main.js', array('jquery'), THEME_VERSION, true);
}
add_action('wp_enqueue_scripts', 'theme_scripts');
EOF

    mkdir -p "$theme_dir/assets/css" "$theme_dir/assets/js" "$theme_dir/template-parts"

    cat > "$theme_dir/assets/css/style.css" << EOF
/*** $name styles ***/
EOF

    cat > "$theme_dir/assets/js/main.js" << EOF
(function() {
    'use strict';
    console.log('$name theme loaded');
})();
EOF

    mkdir -p "$theme_dir/inc"
    cat > "$theme_dir/inc/setup.php" << 'EOF'
<?php
// Theme setup functions
EOF

    log_success "Theme '$name' created at $theme_dir"
    echo ""
    echo "Activate with: ./matrix shell wp theme activate $name"
}

scaffold_plugin() {
    local name="${1:-}"

    if [[ -z "$name" ]]; then
        log_error "Usage: ./matrix scaffold plugin <name>"
        return 1
    fi
    if [[ ! "$name" =~ ^[a-zA-Z][a-zA-Z0-9_-]*$ ]]; then
        log_error "Invalid plugin name: $name"
        return 1
    fi

    local plugins_dir="$PROJECT_ROOT/wp_content/plugins"
    local plugin_dir="$plugins_dir/$name"
    local plugin_file="$plugin_dir/$name.php"

    if [[ -d "$plugin_dir" ]]; then
        log_error "Plugin directory already exists: $plugin_dir"
        return 1
    fi

    log_info "Creating plugin '$name'..."
    mkdir -p "$plugin_dir/includes" "$plugin_dir/assets/css" "$plugin_dir/assets/js"

    cat > "$plugin_file" << EOF
<?php
/**
 * Plugin Name: $name
 * Description: Custom plugin created with SiteMatrix.
 * Version: 1.0.0
 * Author: Developer
 * Text Domain: $name
 */

defined('ABSPATH') || exit;

define('WM_PLUGIN_${name//-/_}_VERSION', '1.0.0');
EOF

    cat > "$plugin_dir/includes/index.php" << 'EOF'
<?php
// Silence is golden.
EOF

    log_success "Plugin '$name' created at $plugin_dir"
}

scaffold_child_theme() {
    local name="${1:-}"

    if [[ -z "$name" ]]; then
        log_error "Usage: ./matrix scaffold child <name>"
        return 1
    fi
    if [[ ! "$name" =~ ^[a-zA-Z][a-zA-Z0-9_-]*$ ]]; then
        log_error "Invalid child theme name: $name"
        return 1
    fi

    local themes_dir="$PROJECT_ROOT/wp_content/themes"
    local theme_dir="$themes_dir/$name"

    if [[ -d "$theme_dir" ]]; then
        log_error "Child theme directory already exists: $theme_dir"
        return 1
    fi

    log_info "Creating child theme '$name'..."
    mkdir -p "$theme_dir"

    cat > "$theme_dir/style.css" << EOF
/*
Theme Name: $name
Template: parent-theme
Description: Child theme created with SiteMatrix
Version: 1.0.0
Text Domain: $name
*/
EOF

    cat > "$theme_dir/functions.php" << 'EOF'
<?php
defined('ABSPATH') || exit;
EOF

    log_success "Child theme '$name' created at $theme_dir"
}

# apply_preset / list_presets now live in scripts/presets-lib.sh
# (presets-as-files: config/presets/<name>.sh defines preset_* hooks).

# Apply multisite conversion to an installed site.
# Usage: apply_multisite <site> <subdirectory|subdomain>
# Runs wp core multisite-install via the on-demand WP-CLI path, then writes
# MULTISITE markers into wp-config.php (insert-if-absent), generates the
# per-stack rewrite rules, and prints hosts lines for subdomain mode.
apply_multisite() {
    local site="${1:-}"
    local mode="${2:-subdirectory}"

    if [[ -z "$site" ]]; then
        log_error "Usage: apply_multisite <site> [subdirectory|subdomain]"
        return 1
    fi

    local subdomains=0
    [[ "$mode" == "subdomain" ]] && subdomains=1
    local site_dir="$PROJECT_ROOT/wp_$site"
    local port
    port=$(get_site_port "$site")

    # Convert via WP-CLI (single invocation; ordering asserted by tests).
    run_wp_cli "$site" core multisite-install \
        --url="http://${HOST_IP:-localhost}:${port:-80}" \
        --title="WordPress Multisite" \
        --subdomains=$subdomains \
        --admin_user=admin --admin_password=admin \
        --admin_email=admin@example.com --allow-root 2>/dev/null || true

    # Insert-if-absent wp-config markers (never duplicate; round-trip safe).
    local wp_config="$site_dir/wp-config.php"
    if [[ -f "$wp_config" ]] && ! grep -q "define( 'MULTISITE', true )" "$wp_config"; then
        cat >> "$wp_config" << EOF

// Enable Multisite
define( 'WP_ALLOW_MULTISITE', true );
define( 'MULTISITE', true );
define( 'SUBDOMAIN_INSTALL', $( [[ $subdomains -eq 1 ]] && echo true || echo false ) );
define( 'DOMAIN_CURRENT_SITE', '${site}.test' );
define( 'PATH_CURRENT_SITE', '/' );
define( 'SITE_ID_CURRENT_SITE', 1 );
define( 'BLOG_ID_CURRENT_SITE', 1 );
EOF
    fi

    # Per-stack rewrite rules.
    generate_multisite_rewrite "$site" "$mode"

    # Subdomain mode: print the hosts lines the user must add (no DNS magic).
    if [[ "$mode" == "subdomain" ]]; then
        local lan_ip
        lan_ip=$(get_lan_ip)
        echo "Add these lines to /etc/hosts for subdomain multisite:"
        echo "  ${lan_ip} ${site}.test"
        echo "  ${lan_ip} *.${site}.test"
    fi

    log_success "Multisite ($mode) enabled for '$site'"
}

# Whether a site's wp-config carries the MULTISITE marker.
site_is_multisite() {
    local site="${1:-}"
    [[ -n "$site" && -f "$PROJECT_ROOT/wp_$site/wp-config.php" ]] && \
        grep -q "define( 'MULTISITE', true )" "$PROJECT_ROOT/wp_$site/wp-config.php"
}

# Read a site's multisite mode from the SUBDOMAIN_INSTALL marker.
# Echoes 'subdirectory' | 'subdomain' | '' (not multisite).
site_multisite_mode() {
    local site="${1:-}"
    local wp_config="$PROJECT_ROOT/wp_$site/wp-config.php"
    if [[ -f "$wp_config" ]] && grep -q "define( 'MULTISITE', true )" "$wp_config"; then
        if grep -q "define( 'SUBDOMAIN_INSTALL', true )" "$wp_config"; then
            echo "subdomain"
        else
            echo "subdirectory"
        fi
    fi
}

# Generate per-stack multisite rewrite rules for a site.
# nginx: appends a marker block to config/nginx/<site>.conf
# apache: appends rules to the site's .htaccess
generate_multisite_rewrite() {
    local site="${1:-}"
    local mode="${2:-subdirectory}"
    local site_dir="$PROJECT_ROOT/wp_$site"

    # nginx (always generated when the conf exists; apache sites have none)
    local nginx_conf="$PROJECT_ROOT/config/nginx/$site.conf"
    if [[ -f "$nginx_conf" ]] && ! grep -q "BEGIN WordPress Multisite" "$nginx_conf"; then
        cat >> "$nginx_conf" << 'EOF'

    # BEGIN WordPress Multisite (subdirectory mode)
    location ~ ^/wp-files(/.*|$) {
        rewrite ^/wp-files(/.*)$ /wp-files/$1 last;
    }
    # Upload handling for mapped sites
    rewrite ^/files/(.+)$ /wp-includes/ms-files.php?file=$1 last;
    # END WordPress Multisite
EOF
    fi

    # Apache .htaccess
    local htaccess="$site_dir/.htaccess"
    if [[ -f "$htaccess" ]] && ! grep -q "BEGIN WordPress Multisite" "$htaccess"; then
        cat >> "$htaccess" << 'EOF'

# BEGIN WordPress Multisite
RewriteEngine On
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
RewriteRule ^([_0-9a-zA-Z-]+/)?wp-admin$ $1wp-admin/ [R=301,L]
# END WordPress Multisite
EOF
    fi
}

watch_site() {
    local site_name="${1:-}"
    local site_path=""

    if [[ -z "$site_name" ]]; then
        log_error "Usage: ./matrix watch <site-name>"
        return 1
    fi

    if [[ ! -d "$PROJECT_ROOT/wp_$site_name" ]]; then
        log_error "Site not found: $site_name"
        return 1
    fi

    site_path="$PROJECT_ROOT/wp_$site_name"
    log_info "Watching $site_path for changes..."

    local last_check=0
    local poll_interval=2

    if command -v fswatch >/dev/null 2>&1; then
        log_info "Using fswatch for file monitoring"
        fswatch -r "$site_path" --exclude=.git --exclude=node_modules --exclude=vendor --exclude=cache 2>/dev/null | while read -r event; do
            echo "Change detected: $event"
            $CONTAINER_RUNTIME exec "wp_$site_name" php -r "opcache_get_status()['opcache_enabled'] && opcache_reset();" 2>/dev/null || true
        done
    else
        log_info "Using polling mode (install fswatch for better performance)"
        log_info "Press Ctrl+C to stop watching"
        while true; do
            local current_mtime=$(find "$site_path/wp-content" -type f -name "*.php" -mmin -"$poll_interval" 2>/dev/null | head -1 | xargs stat -f %m 2>/dev/null || echo "0")
            if [[ "$current_mtime" != "$last_check" && "$last_check" != "0" ]]; then
                echo "Change detected, clearing OPcache..."
                $CONTAINER_RUNTIME exec "wp_$site_name" php -r "if (function_exists('opcache_get_status') && opcache_get_status()) { opcache_reset(); echo 'OPcache cleared'; }" 2>/dev/null || echo "Could not clear OPcache"
            fi
            last_check=$current_mtime
            sleep "$poll_interval"
        done
    fi
}

# list_presets now lives in scripts/presets-lib.sh
# (iterates config/presets/*.sh and prints each file's description).

# Frontend management

# PIDs holding port 8500, plus any `node app.js` from our frontend dir.
# lsof is not installed on every host (Manjaro base) and silently returned
# empty, so port detection never fired and start crashed with EADDRINUSE.
# ss -tlnp reports pid= only for our own sockets, which is all we need -
# the frontend runs as the same user. pgrep covers the npm->node wrapper
# mismatch: $! records npm's PID while the listener is its node child.
frontend_port_pids() {
    local pids=""
    if command -v lsof > /dev/null 2>&1; then
        pids=$(lsof -ti:8500 2>/dev/null)
    elif command -v ss > /dev/null 2>&1; then
        pids=$(ss -tlnp 2>/dev/null | grep ':8500 ' | grep -oE 'pid=[0-9]+' | cut -d= -f2)
    fi
    pids="$pids $(pgrep -f "node app.js" 2>/dev/null | tr '\n' ' ')"
    echo "$pids" | tr ' ' '\n' | sed '/^$/d' | sort -u | tr '\n' ' '
}

manage_frontend() {
    local action="${1:-}"

    if [[ -z "$action" ]]; then
        log_error "Usage: ./matrix frontend <start|stop|restart|status>"
        return 1
    fi

    local frontend_dir="$PROJECT_ROOT/frontend"
    local pid_file="$PROJECT_ROOT/.frontend.pid"
    local log_file="$PROJECT_ROOT/logs/frontend.log"

    # Create logs directory if it doesn't exist
    mkdir -p "$(dirname "$log_file")"

    case "$action" in
        "start")
            # Check if port 8500 is already in use
            local port_pids=$(frontend_port_pids)
            if [[ -n "$port_pids" ]]; then
                # Check if it's already our frontend
                if [[ -f "$pid_file" ]]; then
                    local existing_pid=$(cat "$pid_file")
                    # Check if any of the port PIDs match our expected PID
                    local match=false
                    for pid in $port_pids; do
                        if [[ "$pid" == "$existing_pid" ]]; then
                            match=true
                            break
                        fi
                    done
                    if $match && ps -p "$existing_pid" > /dev/null 2>&1; then
                        log_warning "Frontend is already running on port 8500 (PID: $existing_pid)"
                        return 0
                    fi
                fi
                # Port is in use by leftover processes - kill them all
                log_warning "Cleaning up leftover processes on port 8500..."
                for pid in $port_pids; do
                    kill -9 "$pid" 2>/dev/null || true
                done
                sleep 1
            fi

            if [[ ! -d "$frontend_dir" ]]; then
                log_error "Frontend directory not found: $frontend_dir"
                return 1
            fi

            log_info "Starting frontend..."
            cd "$frontend_dir" || return 1

            # node directly, not `npm start`: $! is then the actual
            # listener PID, so the pidfile matches what port detection
            # (frontend_port_pids) finds and "already running" detection
            # works. Via npm, the pidfile held npm's PID while the socket
            # belonged to npm's node child - they never matched.
            MATRIX_LAN_IP="$HOST_IP" PORT=8500 node app.js > "$log_file" 2>&1 &
            local pid=$!
            echo $pid > "$pid_file"

            sleep 2
            if ps -p "$pid" > /dev/null 2>&1; then
                log_success "Frontend started: http://$HOST_IP:8500 (PID: $pid)"
            else
                log_error "Failed to start frontend. Check logs: $log_file"
                rm -f "$pid_file"
                tail -20 "$log_file" 2>/dev/null || true
                return 1
            fi
            ;;
        "stop")
            # Check if frontend is running (by PID file or by port)
            local is_running=false
            local current_pid=""

            if [[ -f "$pid_file" ]]; then
                current_pid=$(cat "$pid_file")
                if ps -p "$current_pid" > /dev/null 2>&1; then
                    is_running=true
                fi
            fi

            # Kill ALL processes on port 8500 (handle stale/leftover processes)
            local port_pids=$(frontend_port_pids)
            if [[ -n "$port_pids" ]]; then
                is_running=true
                if [[ -z "$current_pid" ]]; then
                    current_pid=$(echo "$port_pids" | awk '{print $1}')
                fi
            fi

            if ! $is_running; then
                log_warning "Frontend is not running"
                rm -f "$pid_file"
                return 0
            fi

            log_info "Stopping frontend (PID: $current_pid)..."
            # Kill all found PIDs on port 8500
            for pid in $port_pids; do
                kill "$pid" 2>/dev/null || true
            done
            sleep 1

            for pid in $port_pids; do
                if ps -p "$pid" > /dev/null 2>&1; then
                    kill -9 "$pid" 2>/dev/null || true
                fi
            done

            rm -f "$pid_file"
            log_success "Frontend stopped"
            ;;
        "restart")
            log_info "Restarting frontend..."
            manage_frontend stop
            sleep 1
            manage_frontend start
            ;;
        "status")
            local is_running=false
            local pid=""

            if [[ -f "$pid_file" ]]; then
                pid=$(cat "$pid_file")
                if ps -p "$pid" > /dev/null 2>&1; then
                    is_running=true
                fi
            fi

            # Also check by port (fallback to ss if lsof missing)
            if ! $is_running; then
                if command -v lsof > /dev/null 2>&1; then
                    local port_pid=$(lsof -ti:8500 2>/dev/null)
                elif command -v ss > /dev/null 2>&1; then
                    local port_pid=$(ss -tlnp 2>/dev/null | awk '/:8500 /{print $NF}' | grep -oE 'pid=[0-9]+' | cut -d= -f2)
                fi
                if [[ -n "$port_pid" ]]; then
                    is_running=true
                    pid=$port_pid
                fi
            fi

            if $is_running; then
                echo "Frontend: Running (http://$HOST_IP:8500) - PID: $pid"
            else
                echo "Frontend: Stopped"
            fi
            ;;
        *)
            log_error "Unknown action: $action"
            log_info "Available: start, stop, restart, status"
            return 1
            ;;
    esac
}

repair_env() {
    local site_name="${1:-}"
    local fixed_count=0
    local checked_count=0

    log_info "Scanning for issues..."

    if [[ ! -f "$COMPOSE_FILE" ]]; then
        log_warning "docker-compose.yml missing - recreating base file..."
        rebuild_compose_base
        fixed_count=$((fixed_count + 1))
        log_success "Created base docker-compose.yml"
    fi

    if [[ ! -d "$PROJECT_ROOT/config/nginx" ]]; then
        mkdir -p "$PROJECT_ROOT/config/nginx"
        log_warning "Created missing config/nginx/ directory"
        fixed_count=$((fixed_count + 1))
    fi

    if [[ ! -f "$PROJECT_ROOT/config/nginx/default.conf" ]]; then
        cat > "$PROJECT_ROOT/config/nginx/default.conf" << 'NGINXEOF'
server {
    listen 80 default_server;
    server_name _;
    root /var/www/html;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass localhost:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
NGINXEOF
        log_success "Created default nginx config"
        fixed_count=$((fixed_count + 1))
    fi

    if [[ ! -f "$PROJECT_ROOT/.env" ]]; then
        log_warning ".env file missing - creating default..."
        cat > "$PROJECT_ROOT/.env" << 'ENVEOF'
# WordPress Environment
MYSQL_USER=wp_user
MYSQL_PASSWORD=wp_password
MYSQL_ROOT_PASSWORD=root_password
WP_DEBUG=true
ENVEOF
        log_success "Created .env file"
        chmod 600 "$PROJECT_ROOT/.env"
        fixed_count=$((fixed_count + 1))
    fi
    
    mkdir -p "$PROJECT_ROOT/logs"

    local sites_tmp
    sites_tmp=$(mktemp)
    get_sites > "$sites_tmp"
    local site_list
    site_list=$(cat "$sites_tmp")
    rm -f "$sites_tmp"

    if [[ -n "$site_name" ]]; then
        if ! site_exists "$site_name"; then
            log_error "Site '$site_name' not found (no wp_$site_name directory)"
            return 1
        fi
        site_list="$site_name"
    fi

    while IFS= read -r site || [[ -n "$site" ]]; do
        [[ -z "$site" ]] && continue
        if ! validate_site_name "$site" >/dev/null 2>&1; then
            log_warning "[$site] Skipping — invalid site name"
            continue
        fi
        checked_count=$((checked_count + 1))
        local site_fixed=0

        local nginx_conf="$PROJECT_ROOT/config/nginx/$site.conf"
        local site_stack
        site_stack=$(get_site_stack "$site")
        if [[ "$site_stack" == "nginx" && ! -f "$nginx_conf" ]]; then
            log_warning "[$site] Missing nginx config"
            generate_nginx_conf "$site" "$(get_site_type "$site")"
            log_success "[$site] Created nginx config"
            site_fixed=$((site_fixed + 1))
        fi

        local in_compose=false
        if site_in_compose "$site"; then
            in_compose=true
        fi

        if ! $in_compose; then
            log_warning "[$site] Missing from docker-compose.yml"

            local php_version="$DEFAULT_PHP_VERSION"
            if [[ -f "$PROJECT_ROOT/wp_$site/wp-includes/version.php" ]]; then
                local req_php
                req_php=$(grep "required_php_version" "$PROJECT_ROOT/wp_$site/wp-includes/version.php" 2>/dev/null | grep -oE '[0-9]+\.[0-9]+' | head -1 || true)
                if [[ -n "$req_php" ]]; then
                    case "$req_php" in
                        7.*) php_version="7.4" ;;
                        8.0*) php_version="8.0" ;;
                        8.1*) php_version="8.1" ;;
                        8.2*) php_version="8.2" ;;
                        *) php_version="$DEFAULT_PHP_VERSION" ;;
                    esac
                fi
            fi

            local repair_stack="nginx"
            if [[ -f "$PROJECT_ROOT/wp_$site/.matrix-stack" ]]; then
                repair_stack=$(tr -d '[:space:]' < "$PROJECT_ROOT/wp_$site/.matrix-stack")
            fi
            case "$repair_stack" in
                apache|nginx) ;;
                *) repair_stack="nginx" ;;
            esac

            # Non-wp sites are nginx-only and must not be re-registered as
            # wordpress:phpX-fpm services (wrong image + WRONG webroot).
            local repair_type
            repair_type=$(get_site_type "$site")
            if [[ "$repair_type" != "wp" ]]; then
                repair_stack="nginx"
            fi

            local port
            port=$(get_next_port)

            if [[ "$repair_stack" == "apache" ]]; then
                compose_add_site "$site" "$php_version" "$port" "" "apache" "$repair_type"
                matrix_site_build_if_apache "$site" || true
                log_success "[$site] Added Apache stack to docker-compose.yml (PHP $php_version, port $port)"
            else
                if [[ ! -f "$nginx_conf" ]]; then
                    generate_nginx_conf "$site" "$repair_type"
                fi
                compose_add_site "$site" "$php_version" "$port" "$nginx_conf" "nginx" "$repair_type"
                log_success "[$site] Added to docker-compose.yml (PHP $php_version, port $port, type $repair_type)"
            fi
            site_fixed=$((site_fixed + 1))
        fi

        # grav (and any no-db type) must never get a database created.
        if site_type_uses_db "$(get_site_type "$site")"; then
        if compose_ps_names 2>/dev/null | grep -q "wp_db"; then
            local db_exists
            db_exists=$($DOCKER_COMPOSE exec -T -e MYSQL_PWD="${MYSQL_ROOT_PASSWORD:-root}" db mysql -u root \
                -sN -e "SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME='${site}_db'" 2>/dev/null </dev/null || true)
            if [[ -z "$db_exists" ]]; then
                log_warning "[$site] Database '${site}_db' missing"
                $DOCKER_COMPOSE exec -T -e MYSQL_PWD="${MYSQL_ROOT_PASSWORD:-root}" db mysql -u root \
                    -e "CREATE DATABASE IF NOT EXISTS \`${site}_db\`; GRANT ALL PRIVILEGES ON \`${site}_db\`.* TO '${MYSQL_USER:-wp_user}'@'%'; FLUSH PRIVILEGES;" 2>/dev/null </dev/null || true
                log_success "[$site] Created database '${site}_db'"
                site_fixed=$((site_fixed + 1))
            fi
        fi
        fi

        mkdir -p "$PROJECT_ROOT/logs/wp_$site"

        if [[ $site_fixed -gt 0 ]]; then
            fixed_count=$((fixed_count + site_fixed))
        else
            log_info "[$site] OK"
        fi
    done <<< "$site_list"

    echo ""
    if [[ $fixed_count -gt 0 ]]; then
        log_success "Repair complete: $fixed_count issue(s) fixed across $checked_count site(s)"
        log_info "Run './matrix start <site>' or './matrix start' to apply changes"
    else
        log_success "All $checked_count site(s) are healthy - no issues found"
    fi
    log_activity "REPAIR" "${site_name:-all}" "$fixed_count issue(s) fixed"
}

rebuild_compose_base() {
    cat > "$COMPOSE_FILE" << 'EOF'
networks:
  wp-net:
    driver: bridge

services:
  # Database
  db:
    image: mysql:8.0
    container_name: wp_db
    restart: unless-stopped
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: wp_main
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - wp_db_data:/var/lib/mysql
    networks:
      - wp-net
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      timeout: 20s
      retries: 10

  # Cache
  redis:
    image: redis:alpine
    container_name: wp_redis
    restart: unless-stopped
    networks:
      - wp-net
    command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru

  # Database Management
  phpmyadmin:
    image: phpmyadmin/phpmyadmin:5.2.1
    container_name: wp_phpmyadmin
    restart: unless-stopped
    ports:
      - "8200:80"
    environment:
      PMA_HOST: db
      PMA_USER: ${MYSQL_USER:-wp_user}
      PMA_PASSWORD: ${MYSQL_PASSWORD:-wp_password}
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-root}
    networks:
      - wp-net
    depends_on:
      - db

  # Email Testing
  mailpit:
    image: axllent/mailpit:latest
    container_name: wp_mailpit
    restart: unless-stopped
    ports:
      - "1025:1025"
      - "8025:8025"
    networks:
      - wp-net

  # Code Quality Tools
  phpcs:
    image: wpengine/phpcs:latest
    container_name: wp_phpcs
    volumes:
      - ./:/workspace:ro
    working_dir: /workspace
    networks:
      - wp-net
    profiles:
      - tools

  phpstan:
    image: ghcr.io/phpstan/phpstan:latest
    container_name: wp_phpstan
    volumes:
      - ./:/project:ro
    working_dir: /project
    networks:
      - wp-net
    profiles:
      - tools

  # Development Tools
  wp-cli:
    image: wordpress:cli
    container_name: wp_cli
    volumes:
      - ./:/var/www/html:rw
    working_dir: /var/www/html
    networks:
      - wp-net
    profiles:
      - tools
    command: ["tail", "-f", "/dev/null"]


volumes:
  wp_db_data:
EOF
}

# Main command dispatcher
main() {
    if [[ $# -eq 0 ]]; then
        show_help
        return
    fi
    
    local command="$1"
    shift

    local json_flag=false
    local filtered_args=()
    for arg in "$@"; do
        if [[ "$arg" == "--json" ]]; then
            json_flag=true
        else
            filtered_args+=("$arg")
        fi
    done
    if [[ "$json_flag" == true ]]; then
        JSON_OUTPUT=true
        json_log_override
    fi
    if [[ ${#filtered_args[@]} -gt 0 ]]; then
        set -- "${filtered_args[@]}"
    fi

    case "$command" in
        # --- Setup ---
        "setup")
            setup_env "$@"
            ;;
        # --- Dashboard token ---
        "token")
            local env_file="$PROJECT_ROOT/frontend/.env"
            if [[ "${1:-}" == "--rotate" ]]; then
                if [[ ! -d "$PROJECT_ROOT/frontend" ]]; then
                    log_error "Frontend directory not found"
                    exit 1
                fi
                local new_token
                new_token=$(openssl rand -hex 16 2>/dev/null) || {
                    log_error "openssl not available"
                    exit 1
                }
                if [[ -f "$env_file" ]] && grep -q '^MATRIX_DASHBOARD_TOKEN=' "$env_file"; then
                    sed -i "s/^MATRIX_DASHBOARD_TOKEN=.*/MATRIX_DASHBOARD_TOKEN=$new_token/" "$env_file"
                else
                    echo "MATRIX_DASHBOARD_TOKEN=$new_token" >> "$env_file"
                fi
                log_success "New token generated. Restart the frontend to apply:"
                log_info "  ./matrix frontend restart"
            fi
            if [[ ! -f "$env_file" ]]; then
                log_error "No frontend/.env — dashboard is loopback-only (no token)"
                exit 1
            fi
            local token
            token=$(grep '^MATRIX_DASHBOARD_TOKEN=' "$env_file" | cut -d= -f2)
            if [[ -z "$token" ]]; then
                log_error "MATRIX_DASHBOARD_TOKEN not set — dashboard is loopback-only"
                log_info "Generate one: ./matrix token --rotate"
                exit 1
            fi
            echo "MATRIX_DASHBOARD_TOKEN=$token"
            ;;
        # --- Site + environment management ---
        "start")
            if [[ -n "${1:-}" ]]; then
                local site_name="${1:-}"
                validate_site_name "$site_name" || exit 1
                if [[ ! -d "$PROJECT_ROOT/wp_${site_name}" ]]; then
                    log_error "Site '$site_name' not found"
                    exit 1
                fi

                cmd_start_site "$site_name"
            else
                start_env
            fi
            ;;
        "stop")
            # Check if a site name was provided
            if [[ -n "${1:-}" ]]; then
                # Stop a specific site
                local site_name="${1:-}"
                validate_site_name "$site_name" || exit 1
                if [[ ! -d "$PROJECT_ROOT/wp_${site_name}" ]]; then
                    log_error "Site '$site_name' not found"
                    exit 1
                fi

                log_info "Stopping site '$site_name'..."
                matrix_site_stop "$site_name"
                log_success "Site '$site_name' stopped"
                log_activity "STOP" "$site_name" "Stopped manually"
            else
                # Stop entire environment
                stop_env
            fi
            ;;
        "restart")
            if [[ -n "${1:-}" ]]; then
                local site_name="${1:-}"
                validate_site_name "$site_name" || exit 1
                if [[ ! -d "$PROJECT_ROOT/wp_${site_name}" ]]; then
                    log_error "Site '$site_name' not found"
                    exit 1
                fi
                log_info "Restarting site '$site_name'..."
                matrix_site_restart "$site_name"
                log_success "Site '$site_name' restarted"
                show_urls "$site_name"
            else
                stop_env
                start_env
            fi
            ;;
        "logs")
            show_logs "$@"
            ;;
        "create")
            create_site "$@"
            ;;
        "backup")
            cmd_backup "$@"
            ;;
        "cron-install")
            cron_install "$@"
            ;;
        "cron-remove")
            cron_remove "$@"
            ;;
        "restore")
            restore_site "$@"
            ;;
        "list"|"ls")
            if [[ "$JSON_OUTPUT" == true ]]; then
                list_sites_json
            else
                list_sites "$@"
            fi
            ;;
        "status")
            if [[ "$JSON_OUTPUT" == true ]]; then
                show_status_json
            else
                show_status "$@"
            fi
            ;;
        # --- Site lifecycle ---
        "remove"|"rm"|"delete")
            remove_site "$@"
            ;;
        "edit"|"update-site")
            edit_site "$@"
            ;;
        "rename")
            rename_site "$@"
            ;;
        "clone")
            "$PROJECT_ROOT/scripts/clone.sh" "$@"
            ;;
        "reset")
            "$PROJECT_ROOT/scripts/reset.sh" "$@"
            ;;
        # --- Site operations ---
        "info")
            if [[ "$JSON_OUTPUT" == true ]]; then
                show_info_json "$@"
            else
                show_urls "$@"
            fi
            ;;
        "fix")
            log_warning "Auto-fix is not yet implemented. Use './matrix check <site>' to identify issues."
            ;;
        "shell")
            access_shell "$@"
            ;;
        "wp"|"wp-cli")
            run_wp_cli "$@"
            ;;
        "url"|"urls")
            show_urls "$@"
            ;;
        "rest")
            rest_site "$@"
            ;;
        # --- Environment ---
        "install")
            install_env "$@"
            ;;
        "repair")
            repair_env "$@"
            ;;
        "clean")
            clean_env "$@"
            ;;
        "health")
            "$PROJECT_ROOT/scripts/health-check.sh"
            ;;
        "doctor")
            cmd_doctor "$@"
            ;;
        "export")
            export_site "$@"
            ;;
        "import")
            import_site "$@"
            ;;
        "share")
            share_site "$@"
            ;;
        "test")
            compat_test "$@"
            ;;
        "mail")
            if command -v open >/dev/null 2>&1; then
                open "http://$HOST_IP:8025"
            else
                echo "Open http://$HOST_IP:8025 in your browser"
            fi
            ;;
        "phpmyadmin")
            local pma_url="http://$HOST_IP:8200"
            if [[ -n "${1:-}" ]]; then
                local site_name="${1:-}"
                validate_site_name "$site_name" || exit 1
                pma_url="${pma_url}?db=${site_name}_db"
            fi
            if command -v open >/dev/null 2>&1; then
                open "$pma_url"
            else
                echo "Open $pma_url in your browser"
            fi
            ;;
        # --- Database ---
        "import-db")
            import_db "$@"
            ;;
        "export-db")
            export_db "$@"
            ;;
        # --- Code quality ---
        "check"|"quality")
            run_checks "$@"
            ;;
        "test")
            run_checks "$@"
            ;;
        # --- Development tools ---
        "frontend")
            manage_frontend "$@"
            ;;
        "xdebug")
            configure_xdebug "$@"
            ;;
        "scaffold")
            scaffold_project "$@"
            ;;
        "preset")
            list_presets "$@"
            ;;
        "watch")
            watch_site "$@"
            ;;
        # --- Utilities ---
        "update"|"update-core")
            "$PROJECT_ROOT/scripts/update-core.sh" "$@"
            ;;
        "cache"|"cache-clear")
            "$PROJECT_ROOT/scripts/cache-clear.sh" "$@"
            ;;
        "search-replace")
            "$PROJECT_ROOT/scripts/search-replace.sh" "$@"
            ;;
        "optimize")
            optimize_site "$@"
            ;;
        "ssl")
            cmd_ssl "$@"
            ;;
        "domain")
            cmd_domain "$@"
            ;;
        "help"|"-h"|"--help")
            show_help
            ;;
        *)
            log_error "Unknown command: $command"
            show_help
            return 1
            ;;
    esac
}

# Only run the CLI when executed directly — sourcing the script (for tests)
# must not trigger command dispatch.
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
    main "$@"
fi