cpanel-migrate-addon.sh

#!/usr/bin/env bash
# cpanel-migrate-addon.sh — move an addon domain (and its subdomain children)
# between two cPanel accounts on the SAME server. cPanel does NOT provide a
# native single-call API for this; this script composes the supported
# primitives: rsync + mysqldump + whmapi1 create_subdomain +
# whmapi1 create_parked_domain_for_user + whmapi1 delete_domain.
#
# The script auto-detects every decision point so a single invocation handles
# real-world cases: nested subdomain children, dead external DB hosts referenced
# in wp-config, expired registrations, multiple legacy DB prefix policies,
# stale cPanel JSON error reporting, HEAD-hostile .htaccess, etc.
#
# ----------------------------------------------------------------------------
# WHAT THIS SCRIPT DOES *NOT* DO (migrate these separately!)
# ----------------------------------------------------------------------------
# Email accounts (mailboxes, forwarders, autoresponders, filters, SpamAssassin
#   user config, cPanel-generated DKIM signing keys), FTP accounts, SSH keys,
#   cron jobs, password-protected directories, IP-blocker/hotlink rules,
#   custom Apache handlers/MIME, Softaculous installation metadata, account
#   packages / LVE limits / reseller ACLs, WebDisk accounts, manually-installed
#   SSL certs, DNSSEC keys, cPanel Redirects GUI entries, wildcard subdomains,
#   multi-level subdomain children.
# Read README.md for the complete list.
#
# ----------------------------------------------------------------------------
# DISCLAIMER
# ----------------------------------------------------------------------------
# Provided "as is", no warranty, no liability. Skills IT — Technology Solutions
# and contributors are NOT liable for any damages arising from use of this
# software. Always take a hypervisor-level snapshot (Vultr / AWS / DO /
# Proxmox / etc.) and run --dry-run FIRST. Full disclaimer: LICENSE + README.md.
#
# ----------------------------------------------------------------------------
# SUPPORT / PROFESSIONAL SERVICES
# ----------------------------------------------------------------------------
# Skills IT — Technology Solutions (Brazil)
#   Website: https://skillsit.com.br
#   Email:   contato@skillsit.com.br
#   Phone:   +55 63 3224-4925
# Specialties: cPanel/WHM migrations, mail deliverability (SPF/DKIM/DMARC),
# DNS architecture, hosting automation, WordPress/LSWS performance, MCP / AI.
#
# ----------------------------------------------------------------------------
# KNOWN ISSUES FIXED / COMPENSATED IN THIS SCRIPT
# ----------------------------------------------------------------------------
# A. whmapi1 CLI always exits 0. Real result is in JSON .metadata.result.
#    → whmapi1_must_succeed() parses and validates.
# B. cPanel rejects creating a domain on B while it still exists on A.
#    → remove_source_addon runs BEFORE create_dest_addon.
# C. The required DB prefix per account is NOT always "${user:0:8}_".
#    → get_required_db_prefix() queries uapi Mysql get_restrictions.
# D. Addon with subdomain children fails delete_domain (parent blocked).
#    → detect_subdomain_children() + auto-migrate children first.
# E. DB passwords containing base64 chars (/+=) sometimes hash-mismatch on
#    cPanel's side (not only MYSQL_PWD CLI bug — also mysqli).
#    → safe_random_password() uses alphanumeric only, and db_login_test runs
#      after create; auto-resets via uapi Mysql set_password if login fails.
# F. curl -I (HEAD) returns 403 on sites with defensive .htaccess rules.
#    → smoke_test uses GET with browser UA and scans body.
# G. HTTP 200 can still mean "Database Error" or "erro crítico" page.
#    → body_smoke matches BODY_ERROR_PATTERNS before declaring success.
# H. wp-config.php commonly has commented-out //define lines pointing to dead
#    legacy DBs (ex: olddb.provider-that-shutdown.example.com).
#    → php_extract_constant regex starts with ^[[:space:]]*define (not //).
# I. Subdomain children sometimes live INSIDE the parent docroot.
#    → migrate_subdomain_child detects nesting and skips redundant rsync.
# J. cPanel REGENERATES the DNS zone during create_subdomain /
#    create_parked_domain_for_user. Custom MX, SPF, DKIM, SRV, CNAME get
#    replaced by cPanel defaults. This breaks M365/Google Workspace mail.
#    → backup_dns_zone saves a full JSON dump BEFORE touching anything;
#      restore_dns_custom_records() replays every record AFTER the migration.
# K. cPanel auto-adds the domain to /etc/localdomains, which makes Exim
#    intercept mail that should go to external MX (M365/Google).
#    → configure_exim_routing() moves to /etc/remotedomains if MX external.
# L. whmapi1 URL-decodes '+' in arguments. SPF with "+a +mx" becomes
#    "v=spf1  a  mx" (double spaces, no +).
#    → TXT values encoded with %2B before sending.
# M. Expired domains resolve locally (BIND/PowerDNS has the zone) but NXDOMAIN
#    externally (registrar de-delegated). AutoSSL fails.
#    → check_domain_registration via RDAP (.br) / DoH (others) in preflight.
# N. This server runs PowerDNS with launch=bind backend, not BIND. rndc
#    reload does NOT work. named.service is inactive.
#    → reload_dns_server() detects active backend and uses the right tool.
# O. Silent incomplete restore: some records from backup failed to re-apply
#    and nobody noticed until mail/site broke.
#    → verify_dns_restore_completeness() diffs backup JSON vs live zone and
#      retries missing records; fails the migration if any stay missing.
# P. Serial cPanel regeneration: even after restore, subsequent cPanel actions
#    (AutoSSL, rebuildhttpdconf) can wipe records again.
#    → final_dns_reconciliation() runs at the very end and re-inserts any
#      records that got wiped between step 8c and step 11.
# ----------------------------------------------------------------------------

DEPENDENCIES=(whmapi1 uapi rsync mysqldump mariadb jq curl awk grep getent stat chown chmod mkdir find du df openssl sed)
OPTIONAL_TOOLS=(wp)
SCRIPT_NAME=$(basename "${BASH_SOURCE[0]}")
VERSION="1.4.1"

INSTALL_PREFIX="${INSTALL_PREFIX:-/usr/local/cpanel-migrate-addon}"
LOG_DIR="${INSTALL_PREFIX}/log"
STATE_DIR="${INSTALL_PREFIX}/state"
REPORT_DIR="${INSTALL_PREFIX}/reports"

RED=$'\e[0;31m'
GREEN=$'\e[0;32m'
YELLOW=$'\e[1;33m'
BLUE=$'\e[0;34m'
CYAN=$'\e[0;36m'
BOLD=$'\e[1m'
NC=$'\e[0m'

if [[ -n "${NO_COLOR:-}" ]] || [[ "${TERM:-}" == "dumb" ]]; then
    RED="" GREEN="" YELLOW="" BLUE="" CYAN="" BOLD="" NC=""
fi

LOG_FILE=""
MODE=""          # dry-run | apply | verify | batch
DOMAIN=""
FROM_USER=""
TO_USER=""
SKIP_DB=false
SKIP_SSL=false
FORCE_WP=false
FORCE_STATIC=false
AUTO_YES=false
WITH_SUBS=true       # default: auto-migrate dependent subdomains. Use --no-subs to disable.
STRICT_DNS=false     # treat expired/NXDOMAIN as fatal in preflight
BATCH_FILE=""        # path to a batch file (one domain per line)
QUIET=false          # reduce log chatter

# Smoke test body-content signatures (lower-case) that indicate a broken site.
# Matched via case-insensitive grep on the fetched HTML body.
declare -ra BODY_ERROR_PATTERNS=(
    "database error"
    "error establishing a database connection"
    "há um erro crítico no seu site"
    "there has been a critical error on this website"
    "fatal error"
    "parse error"
    "internal server error"
    "service unavailable"
    "500 internal server error"
)

function usage() {
    cat <<EOM

${BOLD}${SCRIPT_NAME}${NC} v${VERSION} — migrate one addon domain between two cPanel
accounts on the same server.

${BOLD}USAGE${NC}
    # Simplest form — source user auto-detected from /etc/userdomains:
    ${SCRIPT_NAME} --domain=<fqdn> --to=<user> --apply
    ${SCRIPT_NAME} --batch-file=<path> --to=<user> --apply

    # Explicit forms:
    ${SCRIPT_NAME} --domain=<fqdn> --from=<user> --to=<user> --dry-run
    ${SCRIPT_NAME} --domain=<fqdn> --from=<user> --to=<user> --verify

${BOLD}MODES (pick exactly one)${NC}
    --dry-run          Plan only. Prints every command that would run and every
                       file/DB/record that would be touched. No side effects.
    --apply            Execute the migration. Writes ${LOG_DIR}/<domain>-<ts>.log.
    --verify           Deep post-migration health check: DB login via
                       defaults-file (bypasses MYSQL_PWD client bug), WP siteurl
                       via detected table_prefix, body smoke (GET + body error
                       detection), cert SAN coverage, DNS registration status.

${BOLD}REQUIRED${NC}
    --domain=<fqdn>    Addon domain FQDN
         OR
    --batch-file=<p>   File with one domain per line (# and blank lines skipped;
                       per-line format "domain,from,to" also supported)
    --to=<user>        Destination cPanel account

${BOLD}OPTIONAL${NC}
    --from=<user>      Source cPanel account. Auto-detected from /etc/userdomains
                       if omitted.
    --no-subs          When a parent addon has subdomain children, ABORT instead
                       of auto-migrating them. Default behavior is to migrate
                       children first (cPanel rejects parent delete otherwise).
    --strict-dns       Treat expired/NXDOMAIN domains as FATAL (default: WARN).
                       RDAP for .br, Cloudflare DoH otherwise.
    --skip-db          Treat site as static; do not attempt any DB migration
                       even if wp-config.php is present.
    --skip-ssl         Do not call autossl_check. SSL reissue via AutoSSL cron
                       (default 4h) will catch up. If unset, script waits up to
                       \$AUTOSSL_TIMEOUT_SEC (default 120) polling every
                       \$AUTOSSL_POLL_SEC (default 10) and reloads LSWS on cert.
    --force-wp         Force WordPress-flow path even if no wp-config detected.
    --force-static     Force static-flow path even if wp-config present.
    --with-subs        Retained for backward-compat (default is already true).
    --yes              Non-interactive apply (no confirmation prompt).
    --quiet            Reduce log chatter (shows steps + results only).
    -h | --help        This help.
    --version          Print version.

${BOLD}FLOW (apply mode)${NC}
    1  Preflight              validate inputs, disk, ownership, docroot, PHP
                              version, detect subdomain children, domain
                              registration sanity, DB host health, email accts
    2  Snapshot state         rollback plan JSON
    2b DNS backup              .db + whmapi1 dumpzone JSON (authoritative for
                              record replay in step 8c below)
    3  Create dest dir        mkdir + chown
    4  rsync data             -aHAX --delete-after --backup
    5  DB migrate             (WP) dump + create DB/user + restore + wp-config
                              patch + DB login test + auto-reset password
    5b Children (if any)       migrate each subdomain child (rsync, DB, delete
                              source) BEFORE touching parent addon
    6  create_subdomain       whmapi1 creates <domain>.<to>.main_domain
    6b Set PHP version        whmapi1 php_set_vhost_versions preserves EA-PHP
    7  Remove from source     whmapi1 delete_domain (addon + control sub)
    8  create_parked          whmapi1 create_parked_domain_for_user
    8b Recreate children       now that parent is on destination, create sub
                              vhosts and restore their PHP version
    8c DNS restore             re-apply every record from the JSON snapshot via
                              whmapi1 addzonerecord (cPanel wipes custom MX/
                              CNAME/SRV/TXT during steps 6/7 — this puts them
                              back). Handles self-MX removal, A/CNAME
                              collisions, and SPF with '+' URL-encoded as %2B.
    8d Exim routing            if MX is external (M365/Google/etc), mark the
                              domain REMOTE in /etc/remotedomains so the local
                              MTA does not intercept mail.
    8e rebuildhttpdconf       commit vhost changes to LSWS
    9  Cache + reload         clear LSCache, lswsctrl reload
   10  AutoSSL (optional)     start_autossl_check + wait loop up to 120s +
                              reload LSWS when new cert detected
   11  Smoke test (GET body)  UA=browser, detect "Database Error", "erro
                              crítico", "Fatal error", empty body (<80B)
   12  Write final log        ${LOG_DIR}/<domain>-<ts>.log

${BOLD}ROLLBACK${NC}
    On failure during steps 6-8 the script attempts to restore source-side
    state using the snapshot in ${STATE_DIR}. Data already copied to dest is
    NOT deleted automatically; re-running ${SCRIPT_NAME} --apply is idempotent
    for steps 3-5 (rsync in-place) and step 6-7 short-circuits if already done.

${BOLD}DEPENDENCIES${NC}
    Required:  ${DEPENDENCIES[*]}
    Optional:  ${OPTIONAL_TOOLS[*]} (wp-cli used only for WordPress search-replace
               when destination URL differs from source; not needed here since
               we keep the same public FQDN)

${BOLD}EXAMPLES${NC}
    # Trivial — single domain, auto-detect source:
    ${SCRIPT_NAME} --domain=example.com --to=newaccount --apply --yes

    # Dry run to preview everything:
    ${SCRIPT_NAME} --domain=example.com --to=newaccount --dry-run

    # Batch migrate multiple domains with per-line source override support:
    cat > /tmp/list.txt <<EOF
    site1.com
    site2.net,olduser,newuser
    EOF
    ${SCRIPT_NAME} --batch-file=/tmp/list.txt --to=newuser --apply --yes

    # Post-migration deep health check:
    ${SCRIPT_NAME} --domain=example.com --to=newuser --verify

${BOLD}NOT MIGRATED${NC} — handle separately, BEFORE running this script:
    email accounts, FTP users, SSH keys, cron jobs, password-protected
    directories, wildcard subdomains, multi-level subdomain children,
    manually-installed SSL certs, cPanel Redirects GUI entries, DNSSEC keys,
    Softaculous installation metadata, cPanel packages / LVE limits.
    See README.md → "What this script does NOT do".

${BOLD}SUPPORT${NC}
    Skills IT — Technology Solutions (Brazil)
      https://skillsit.com.br | contato@skillsit.com.br | +55 63 3224-4925
    cPanel/WHM migrations, mail deliverability, DNS, hosting automation, AI/MCP.

EOM
    exit 1
}

function main() {
    local cli_mode=""

    while [[ "$#" -gt 0 ]]; do
        case "$1" in
        --domain=*)       DOMAIN="${1#*=}" ;;
        --domain)         shift; DOMAIN="${1:-}" ;;
        --from=*)         FROM_USER="${1#*=}" ;;
        --from)           shift; FROM_USER="${1:-}" ;;
        --to=*)           TO_USER="${1#*=}" ;;
        --to)             shift; TO_USER="${1:-}" ;;
        --batch-file=*)   BATCH_FILE="${1#*=}" ;;
        --batch-file)     shift; BATCH_FILE="${1:-}" ;;
        --dry-run)        cli_mode="dry-run" ;;
        --apply)          cli_mode="apply" ;;
        --verify)         cli_mode="verify" ;;
        --skip-db)        SKIP_DB=true ;;
        --skip-ssl)       SKIP_SSL=true ;;
        --force-wp)       FORCE_WP=true ;;
        --force-static)   FORCE_STATIC=true ;;
        --with-subs)      WITH_SUBS=true ;;   # kept for backward-compat; default already true
        --no-subs)        WITH_SUBS=false ;;
        --strict-dns)     STRICT_DNS=true ;;
        --quiet)          QUIET=true ;;
        --yes|-y)         AUTO_YES=true ;;
        --version)        echo "${SCRIPT_NAME} v${VERSION}"; exit 0 ;;
        -h|--help)        usage ;;
        *) echo "Error: unknown option '$1'" >&2; usage ;;
        esac
        shift
    done

    # Batch mode dispatches early (loops and calls script recursively per domain).
    # --from is optional (auto-detected per-line from /etc/userdomains).
    if [[ -n "$BATCH_FILE" ]]; then
        if [[ -z "$TO_USER" || -z "$cli_mode" ]]; then
            print_error "--batch-file requires --to, and one of --dry-run|--apply|--verify"
            exit 2
        fi
        exit_on_missing_tools "${DEPENDENCIES[@]}"
        batch_run "$cli_mode"
        exit $?
    fi

    if [[ -z "$DOMAIN" || -z "$TO_USER" || -z "$cli_mode" ]]; then
        print_error "--domain (or --batch-file), --to, and one of --dry-run|--apply|--verify are required"
        usage
    fi

    # Auto-detect --from from /etc/userdomains when not provided
    if [[ -z "$FROM_USER" ]]; then
        FROM_USER=$(grep -E "^${DOMAIN}: " /etc/userdomains 2>/dev/null | awk '{print $2}')
        if [[ -z "$FROM_USER" ]]; then
            print_error "could not auto-detect source user for domain '$DOMAIN' (not in /etc/userdomains)"
            print_error "pass --from=<user> explicitly"
            exit 2
        fi
        [[ "$QUIET" != true ]] && echo "ℹ auto-detected --from=${FROM_USER}"
    fi

    validate_input_safety || exit 2

    MODE="$cli_mode"

    # --verify runs against the destination; FROM_USER may legitimately equal
    # TO_USER because the domain has already moved.
    if [[ "$MODE" != "verify" && "$FROM_USER" == "$TO_USER" ]]; then
        print_error "--from and --to cannot be the same user ($FROM_USER)"
        exit 2
    fi

    if [[ "$FORCE_WP" == true && "$FORCE_STATIC" == true ]]; then
        print_error "--force-wp and --force-static are mutually exclusive"
        exit 2
    fi

    exit_on_missing_tools "${DEPENDENCIES[@]}"

    mkdir -p "$LOG_DIR" "$STATE_DIR" || { print_error "cannot create $LOG_DIR / $STATE_DIR"; exit 3; }
    chmod 750 "$LOG_DIR" "$STATE_DIR" 2>/dev/null || true

    local ts; ts=$(date +%Y%m%d-%H%M%S)
    LOG_FILE="${LOG_DIR}/${DOMAIN}-${MODE}-${ts}.log"

    print_header "${SCRIPT_NAME} v${VERSION} — ${MODE^^} mode"
    log_both "Domain:   ${DOMAIN}"
    log_both "From:     ${FROM_USER}"
    log_both "To:       ${TO_USER}"
    log_both "Log file: ${LOG_FILE}"
    log_both "Host:     $(hostname)"
    log_both "Date:     $(date -Is)"
    log_both ""

    case "$MODE" in
        dry-run) run_flow "dry-run" ;;
        apply)   run_flow "apply" ;;
        verify)  run_verify ;;
    esac
}

function run_flow() {
    local exec_mode="$1"

    preflight || { print_error "preflight failed — aborting"; exit 10; }

    if [[ "$exec_mode" == "apply" && "$AUTO_YES" != true ]]; then
        echo ""
        echo -e "${YELLOW}${BOLD}About to migrate ${DOMAIN} from ${FROM_USER} to ${TO_USER}.${NC}"
        read -r -p "Type 'YES' to continue: " confirm
        if [[ "$confirm" != "YES" ]]; then
            log_both "User aborted at confirmation prompt."
            exit 0
        fi
    fi

    snapshot_state "$exec_mode"         || abort_with_rollback 11 "snapshot_state failed"
    backup_dns_zone "$exec_mode"        || abort_with_rollback 18 "backup_dns_zone failed"
    ensure_destination_dir "$exec_mode" || abort_with_rollback 12 "ensure_destination_dir failed"
    rsync_data "$exec_mode"             || abort_with_rollback 13 "rsync_data failed"
    migrate_database "$exec_mode"       || abort_with_rollback 14 "migrate_database failed"

    # If there are subdomain children and --with-subs, migrate each BEFORE
    # touching the parent addon (data+DB copied, source sub deleted).
    if [[ ${#SUBDOMAIN_CHILDREN[@]} -gt 0 && "$WITH_SUBS" == true ]]; then
        local s
        for s in "${SUBDOMAIN_CHILDREN[@]}"; do
            migrate_subdomain_child "$s" "$exec_mode" \
                || abort_with_rollback 19 "migrate_subdomain_child failed for $s"
        done
    fi

    create_dest_subdomain "$exec_mode"  || abort_with_rollback 15 "create_dest_subdomain failed"
    set_dest_php_version "$exec_mode"   || log_warn "set_dest_php_version returned non-zero (non-fatal)"
    remove_source_addon "$exec_mode"    || abort_with_rollback 17 "remove_source_addon failed"
    create_dest_addon "$exec_mode"      || abort_with_rollback 16 "create_dest_addon failed"
    post_create_subdomain_children "$exec_mode" || log_warn "post_create_subdomain_children had warnings"
    restore_dns_custom_records "$exec_mode"     || log_warn "restore_dns_custom_records had warnings"
    verify_dns_restore_completeness "$exec_mode" || log_warn "DNS verify failed — manual review required"
    reload_dns_server
    configure_exim_routing "$exec_mode"         || log_warn "configure_exim_routing had warnings"
    probe_external_mx "$exec_mode"              || log_warn "probe_external_mx had warnings"
    rebuild_httpd_conf "$exec_mode"     || log_warn "rebuild_httpd_conf returned non-zero (non-fatal)"
    cache_reload "$exec_mode"           || log_warn "cache_reload returned non-zero (non-fatal)"
    autossl_reissue "$exec_mode"        || log_warn "autossl_reissue returned non-zero (non-fatal)"
    smoke_test "$exec_mode"             || log_warn "smoke_test returned non-zero"
    final_dns_reconciliation "$exec_mode"       || log_warn "final DNS reconciliation had warnings"

    print_success "${MODE} completed for ${DOMAIN}"
    log_both ""
    log_both "Next steps:"
    log_both "  - Review log: ${LOG_FILE}"
    log_both "  - Verify:     ${SCRIPT_NAME} --domain=${DOMAIN} --from=${FROM_USER} --to=${TO_USER} --verify"
    # Post-migration cleanup hint — the source DB and files are left in place
    # on purpose (for rollback). Once the migration is validated, drop the
    # source DB via uapi (NOT via "mariadb -e DROP DATABASE" directly — that
    # leaves /var/cpanel/databases/dbindex.db.json with orphan entries, which
    # makes JetBackup and cPanel mail the user with "Unknown database" errors).
    if [[ "$MODE" == "apply" && "$SITE_TYPE" == "wordpress" && "$SKIP_DB" != true ]]; then
        log_both ""
        log_both "Once validated, drop the source DB WITH the cPanel API (not mariadb CLI):"
        log_both "  uapi --user=${FROM_USER} Mysql delete_database name=${SRC_DB_NAME}"
        log_both "  uapi --user=${FROM_USER} Mysql delete_user     name=${SRC_DB_USER}"
    fi
    log_both "Source files in /home/${FROM_USER}/${SOURCE_DOCROOT#/home/${FROM_USER}/} were NOT removed —"
    log_both "delete manually after validation: rm -rf '${SOURCE_DOCROOT}'"
}

function preflight() {
    print_step "Preflight checks"

    if ! id "$FROM_USER" &>/dev/null; then
        log_err "user '$FROM_USER' does not exist on this system"
        return 1
    fi
    if ! id "$TO_USER" &>/dev/null; then
        log_err "user '$TO_USER' does not exist on this system"
        return 1
    fi

    local owner
    owner=$(grep -E "^${DOMAIN}: " /etc/userdomains | awk '{print $2}')
    if [[ "$owner" != "$FROM_USER" ]]; then
        log_err "domain '$DOMAIN' is owned by '${owner:-<nobody>}', not '$FROM_USER'"
        return 1
    fi
    log_ok "domain ${DOMAIN} confirmed as addon of ${FROM_USER}"

    local already_in_to
    already_in_to=$(grep -E "^${DOMAIN}: ${TO_USER}\$" /etc/userdomains || true)
    if [[ -n "$already_in_to" ]]; then
        log_err "domain '$DOMAIN' is ALREADY owned by '$TO_USER' — partial migration? Use --verify"
        return 1
    fi

    FROM_MAIN_DOMAIN=$(awk -F': ' '$1=="main_domain"{print $2}' "/var/cpanel/userdata/${FROM_USER}/main" | tr -d '"')
    TO_MAIN_DOMAIN=$(awk -F': ' '$1=="main_domain"{print $2}' "/var/cpanel/userdata/${TO_USER}/main" | tr -d '"')
    if [[ -z "$FROM_MAIN_DOMAIN" || -z "$TO_MAIN_DOMAIN" ]]; then
        log_err "could not resolve main domains (from=$FROM_MAIN_DOMAIN to=$TO_MAIN_DOMAIN)"
        return 1
    fi
    log_ok "from main: ${FROM_MAIN_DOMAIN} | to main: ${TO_MAIN_DOMAIN}"

    SOURCE_CONTROL_SUB="${DOMAIN}.${FROM_MAIN_DOMAIN}"
    DEST_CONTROL_SUB="${DOMAIN}.${TO_MAIN_DOMAIN}"
    log_ok "source control sub: ${SOURCE_CONTROL_SUB}"
    log_ok "dest control sub:   ${DEST_CONTROL_SUB}"

    # documentroot lives in the control-subdomain userdata file (cPanel 132)
    local src_userdata="/var/cpanel/userdata/${FROM_USER}/${SOURCE_CONTROL_SUB}"
    if [[ -f "$src_userdata" ]]; then
        SOURCE_DOCROOT=$(awk '/^documentroot:/{print $2}' "$src_userdata")
    fi
    if [[ -z "${SOURCE_DOCROOT:-}" || ! -d "$SOURCE_DOCROOT" ]]; then
        log_warn "userdata lookup failed — trying filesystem heuristics"
        SOURCE_DOCROOT=$(find_source_docroot) || return 1
    fi
    log_ok "source docroot: $SOURCE_DOCROOT"

    local existing_dest_sub
    existing_dest_sub=$(grep -E "^${DEST_CONTROL_SUB}: ${TO_USER}\$" /etc/userdomains || true)
    if [[ -n "$existing_dest_sub" ]]; then
        log_warn "destination control subdomain ${DEST_CONTROL_SUB} already exists in ${TO_USER}"
    fi

    detect_site_type "$SOURCE_DOCROOT" || return 1

    compute_dest_paths

    local src_size_kb
    src_size_kb=$(du -sk "$SOURCE_DOCROOT" 2>/dev/null | awk '{print $1}')
    local avail_kb
    avail_kb=$(df -k --output=avail "/home" | tail -1)
    local need_kb=$((src_size_kb + (src_size_kb / 10)))
    log_ok "source size: $((src_size_kb/1024)) MB | /home free: $((avail_kb/1024)) MB | needed (+10%): $((need_kb/1024)) MB"
    if [[ $avail_kb -lt $need_kb ]]; then
        log_err "not enough disk in /home"
        return 1
    fi

    if [[ "$SITE_TYPE" == "wordpress" && "$SKIP_DB" != true ]]; then
        detect_db_config "$SOURCE_DOCROOT" || return 1
        # Verify DB host is reachable — if wp-config points to a dead external host
        # (very common legacy setup), fail fast with a clear message instead of
        # silently producing empty dumps later.
        if ! db_host_health "${SRC_DB_HOST:-localhost}"; then
            log_err "DB host '${SRC_DB_HOST}' in wp-config.php is unreachable"
            log_err "  - not resolving or TCP/3306 closed"
            log_err "  - check if wp-config has an uncommented DB_HOST pointing to a dead provider"
            log_err "  - or pass --skip-db if site is effectively dead / manually restorable"
            return 1
        fi
        log_ok "DB host reachable: ${SRC_DB_HOST:-localhost}"
    fi

    detect_php_version

    # Warn loudly about email accounts — this script does not migrate email.
    local mbox_count
    mbox_count=$(detect_email_accounts "$FROM_USER" "$DOMAIN")
    if [[ "$mbox_count" -gt 0 ]]; then
        log_warn "found ${mbox_count} local mailbox(es) under /home/${FROM_USER}/mail/${DOMAIN}/"
        log_warn "this script does NOT migrate email. Move mailboxes manually BEFORE proceeding,"
        log_warn "or accept that email will need to be restored from backup post-migration."
    else
        log_ok "no local mailboxes for ${DOMAIN} — email migration not needed"
    fi

    scan_for_absolute_paths "$SOURCE_DOCROOT"

    # Detect subdomain children that would block parent delete_domain.
    # Default behavior: migrate them automatically (WITH_SUBS=true).
    # Opt-out with --no-subs if someone wants the strict abort-on-dependency mode.
    detect_subdomain_children
    if [[ ${#SUBDOMAIN_CHILDREN[@]} -gt 0 ]]; then
        log_ok "detected ${#SUBDOMAIN_CHILDREN[@]} subdomain children under ${DOMAIN}:"
        local s
        for s in "${SUBDOMAIN_CHILDREN[@]}"; do log_ok "  - $s"; done
        if [[ "$WITH_SUBS" != true ]]; then
            log_err "--no-subs is active and children exist — cannot proceed."
            log_err "remove --no-subs (or remove each subdomain manually) and retry."
            return 1
        fi
        log_ok "will migrate them automatically before the parent (default behavior)"
    else
        log_ok "no subdomain children under ${DOMAIN}"
    fi

    # DNS / registrar sanity (warn by default; fatal with --strict-dns)
    check_domain_registration "$DOMAIN" || return 1

    log_ok "preflight ok"
    return 0
}

function detect_php_version() {
    local src_userdata="/var/cpanel/userdata/${FROM_USER}/${SOURCE_CONTROL_SUB}"
    if [[ -f "$src_userdata" ]]; then
        SOURCE_PHP_VERSION=$(awk '/^phpversion:/{print $2}' "$src_userdata" | tr -d '"' | head -1)
    fi
    if [[ -z "${SOURCE_PHP_VERSION:-}" ]]; then
        # Fallback: ask WHM directly
        SOURCE_PHP_VERSION=$(whmapi1 --output=json php_get_vhost_versions 2>/dev/null \
            | jq -r --arg v "$SOURCE_CONTROL_SUB" '.data.versions[] | select(.vhost==$v) | .version' \
            | head -1)
    fi
    if [[ -z "${SOURCE_PHP_VERSION:-}" ]]; then
        log_warn "could not detect source PHP version; destination will inherit account default"
        SOURCE_PHP_VERSION="inherit"
    else
        log_ok "source PHP version: ${SOURCE_PHP_VERSION}"
    fi
    return 0
}

function scan_for_absolute_paths() {
    local docroot="$1"
    local hits hits_config hits_dropins=""
    # Look in .user.ini, .htaccess, wp-config.php first (cheap recursive grep).
    hits_config=$(grep -rlE "/home/${FROM_USER}/" \
        --include='.user.ini' --include='.htaccess' --include='wp-config.php' \
        "${docroot}" 2>/dev/null || true)
    # Also scan wp-content top-level PHP drop-ins if WP.
    if [[ -d "${docroot}/wp-content" ]]; then
        hits_dropins=$(find "${docroot}/wp-content" -maxdepth 1 -name '*.php' -print0 2>/dev/null \
            | xargs -0r grep -lE "/home/${FROM_USER}/" 2>/dev/null || true)
    fi
    hits=$(printf '%s\n%s\n' "$hits_config" "$hits_dropins" | grep -v '^$' | sort -u)
    if [[ -n "$hits" ]]; then
        log_warn "found absolute paths referencing /home/${FROM_USER}/ in:"
        while IFS= read -r f; do
            [[ -z "$f" ]] && continue
            log_warn "  - $f"
        done <<< "$hits"
        log_warn "these WILL need manual replacement to /home/${TO_USER}/ post-migration"
        log_warn "(the rsync copies them verbatim; php/lsws will resolve against new home)"
    else
        log_ok "no absolute /home/${FROM_USER}/ paths found in config files"
    fi
    return 0
}

function find_source_docroot() {
    local candidates=(
        "/home/${FROM_USER}/public_html/_dominios/_wp/${DOMAIN}"
        "/home/${FROM_USER}/public_html/_dominios/${DOMAIN}"
        "/home/${FROM_USER}/public_html/_dominios/_wp/${DOMAIN%.*}/${DOMAIN}"
        "/home/${FROM_USER}/public_html/${DOMAIN}"
    )
    for c in "${candidates[@]}"; do
        if [[ -d "$c" ]]; then
            echo "$c"
            return 0
        fi
    done
    log_err "could not find source docroot for $DOMAIN — tried: ${candidates[*]}"
    return 1
}

function compute_dest_paths() {
    local path_suffix
    path_suffix="${SOURCE_DOCROOT#/home/${FROM_USER}/}"

    DEST_DOCROOT="/home/${TO_USER}/${path_suffix}"
    DEST_DOCROOT_REL="${path_suffix}"
    log_ok "dest docroot: $DEST_DOCROOT"
    log_ok "dest docroot (relative): $DEST_DOCROOT_REL"
}

function detect_site_type() {
    local docroot="$1"

    if [[ "$FORCE_WP" == true ]]; then
        SITE_TYPE="wordpress"; log_ok "site type forced: wordpress"; return 0
    fi
    if [[ "$FORCE_STATIC" == true ]]; then
        SITE_TYPE="static"; log_ok "site type forced: static"; return 0
    fi
    if [[ -f "${docroot}/wp-config.php" ]]; then
        SITE_TYPE="wordpress"; log_ok "site type: wordpress (wp-config.php found)"; return 0
    fi
    if find "$docroot" -maxdepth 3 -name 'wp-config.php' -print -quit 2>/dev/null | grep -q .; then
        log_warn "wp-config.php found below docroot root — assuming static unless --force-wp"
    fi
    SITE_TYPE="static"
    log_ok "site type: static (no wp-config.php at docroot)"
    return 0
}

function detect_db_config() {
    local docroot="$1"
    local wpc="${docroot}/wp-config.php"

    if [[ ! -f "$wpc" ]]; then
        log_err "wp-config.php not found at $wpc"
        return 1
    fi

    SRC_DB_NAME=$(php_extract_constant "$wpc" DB_NAME)
    SRC_DB_USER=$(php_extract_constant "$wpc" DB_USER)
    SRC_DB_HOST=$(php_extract_constant "$wpc" DB_HOST)

    if [[ -z "$SRC_DB_NAME" || -z "$SRC_DB_USER" ]]; then
        log_err "could not parse DB_NAME/DB_USER from $wpc"
        return 1
    fi
    log_ok "source DB: ${SRC_DB_NAME} @ ${SRC_DB_HOST:-localhost} (user ${SRC_DB_USER})"

    DEST_DB_NAME=$(rename_with_prefix "$SRC_DB_NAME" "$FROM_USER" "$TO_USER")
    DEST_DB_USER=$(rename_with_prefix "$SRC_DB_USER" "$FROM_USER" "$TO_USER")
    if [[ ${#DEST_DB_NAME} -gt 64 ]]; then
        log_err "computed dest DB name '${DEST_DB_NAME}' exceeds 64 chars (MariaDB limit)"
        return 1
    fi
    if [[ ${#DEST_DB_USER} -gt 32 ]]; then
        log_err "computed dest DB user '${DEST_DB_USER}' exceeds 32 chars (MariaDB limit)"
        return 1
    fi
    log_ok "dest DB planned: ${DEST_DB_NAME} (user ${DEST_DB_USER})"
    return 0
}

function php_extract_constant() {
    local file="$1"
    local const="$2"
    # Accept define('X','Y') and define("X","Y"), any whitespace, any quote mix.
    # IMPORTANT: must skip comment lines — //define, #define, * define (in /*  */ blocks).
    # Rule: the first non-blank char on the line must be 'd' of 'define'.
    local line
    line=$(grep -E "^[[:space:]]*define[[:space:]]*\([[:space:]]*['\"]${const}['\"]" "$file" | head -1)
    [[ -z "$line" ]] && return 0
    echo "$line" | sed -n -E "s/.*define[[:space:]]*\([[:space:]]*['\"]${const}['\"][[:space:]]*,[[:space:]]*['\"]([^'\"]*)['\"].*/\1/p"
}

function get_required_db_prefix() {
    # Ask cPanel what prefix the account must use *right now*. This varies by
    # cpanel.config + account age; assuming "${user:0:8}_" is unsafe.
    local user="$1"
    uapi --user="$user" Mysql get_restrictions 2>/dev/null \
        | awk -F': ' '/^[[:space:]]*prefix:/{gsub(/[[:space:]]/,"",$2); print $2; exit}'
}

function rename_with_prefix() {
    # Args: name from_user to_user [from_prefix] [to_prefix]
    # If the prefixes are not passed explicitly, query them via the API.
    local name="$1"
    local from="$2"
    local to="$3"
    local from_pref="${4:-$(get_required_db_prefix "$from")}"
    local to_pref="${5:-$(get_required_db_prefix "$to")}"

    if [[ -z "$from_pref" || -z "$to_pref" ]]; then
        # API failed — fall back to conservative "prepend to_pref" behavior.
        echo "${to:0:8}_${name}"
        return 1
    fi

    # Case 1 — name uses the source account's CURRENT prefix (e.g. legacyuser_wpsite).
    if [[ "$name" == "${from_pref}"* ]]; then
        echo "${to_pref}${name#"${from_pref}"}"
        return 0
    fi
    # Case 2 — name uses the 8-char LEGACY prefix (e.g. leguser_sitename).
    local from_legacy="${from:0:8}_"
    if [[ "$name" == "${from_legacy}"* && "${from_legacy}" != "${from_pref}" ]]; then
        echo "${to_pref}${name#"${from_legacy}"}"
        return 0
    fi
    # Fallback — prepend dest prefix verbatim.
    echo "${to_pref}${name}"
}

function snapshot_state() {
    local exec_mode="$1"
    local state_file="${STATE_DIR}/${DOMAIN}.snapshot.json"
    print_step "Snapshot source state"

    local payload
    payload=$(jq -n \
        --arg domain "$DOMAIN" \
        --arg from "$FROM_USER" \
        --arg to "$TO_USER" \
        --arg source_docroot "$SOURCE_DOCROOT" \
        --arg dest_docroot "$DEST_DOCROOT" \
        --arg source_control_sub "$SOURCE_CONTROL_SUB" \
        --arg dest_control_sub "$DEST_CONTROL_SUB" \
        --arg site_type "$SITE_TYPE" \
        --arg src_db "${SRC_DB_NAME:-}" \
        --arg dest_db "${DEST_DB_NAME:-}" \
        --arg ts "$(date -Is)" \
        '{domain:$domain, from:$from, to:$to, source_docroot:$source_docroot,
          dest_docroot:$dest_docroot, source_control_sub:$source_control_sub,
          dest_control_sub:$dest_control_sub, site_type:$site_type,
          source_db:$src_db, dest_db:$dest_db, snapshot_at:$ts}')

    if [[ "$exec_mode" == "dry-run" ]]; then
        log_both "[DRY] would write: $state_file"
        log_both "[DRY] payload:"
        echo "$payload" | sed 's/^/[DRY]   /' | tee -a "$LOG_FILE"
    else
        echo "$payload" > "$state_file"
        log_ok "wrote snapshot: $state_file"
    fi
    return 0
}

function ensure_destination_dir() {
    local exec_mode="$1"
    print_step "Destination directory"

    local parent
    parent="$(dirname "$DEST_DOCROOT")"

    if run_or_echo "$exec_mode" "mkdir -p '$parent'" && \
       run_or_echo "$exec_mode" "mkdir -p '$DEST_DOCROOT'" && \
       run_or_echo "$exec_mode" "chown -R ${TO_USER}:${TO_USER} '$parent'" && \
       run_or_echo "$exec_mode" "chmod 755 '$DEST_DOCROOT'"; then
        log_ok "destination dir prepared"
        return 0
    fi
    return 1
}

function rsync_data() {
    local exec_mode="$1"
    print_step "rsync data (source -> destination)"

    local excludes=(
        "--exclude=wp-content/cache"
        "--exclude=wp-content/updraft"
        "--exclude=wp-content/backup-*"
        "--exclude=wp-content/uploads/backwpup-*"
        "--exclude=.well-known/acme-challenge"
    )

    local backup_dir
    backup_dir="${STATE_DIR}/rsync-backup-${DOMAIN}-$(date +%s)"
    local cmd="rsync -aHAX --delete-after --backup --backup-dir='${backup_dir}' --info=stats2,progress2 ${excludes[*]} --chown=${TO_USER}:${TO_USER} '${SOURCE_DOCROOT}/' '${DEST_DOCROOT}/'"

    if [[ "$exec_mode" == "dry-run" ]]; then
        log_both "[DRY] would run: $cmd"
        # Use --dry-run of rsync to get the real file count report:
        local real_cmd="rsync -aHAX --delete-after --dry-run --stats ${excludes[*]} '${SOURCE_DOCROOT}/' '${DEST_DOCROOT}/'"
        log_both "[DRY] rsync --dry-run report:"
        eval "$real_cmd" 2>&1 | tee -a "$LOG_FILE" | tail -20
        return 0
    fi

    if eval "$cmd" 2>&1 | tee -a "$LOG_FILE"; then
        log_ok "rsync completed"
        chown -R "${TO_USER}:${TO_USER}" "$DEST_DOCROOT" || log_warn "post-rsync chown -R returned non-zero"
        return 0
    fi
    return 1
}

function migrate_database() {
    local exec_mode="$1"

    if [[ "$SITE_TYPE" != "wordpress" || "$SKIP_DB" == true ]]; then
        print_step "Database migration — SKIPPED (site is ${SITE_TYPE} / skip-db=${SKIP_DB})"
        return 0
    fi

    print_step "Database migration"

    local dump_file="${STATE_DIR}/${DOMAIN}.dump.sql"
    local tmp_pass
    tmp_pass=$(safe_random_password)
    if [[ ${#tmp_pass} -lt 16 ]]; then
        log_err "failed to generate dest DB password"
        return 1
    fi

    local cmds=(
        "mysqldump --single-transaction --quick --routines --triggers --events '${SRC_DB_NAME}' > '${dump_file}'"
        "uapi --user=${TO_USER} Mysql create_database name=${DEST_DB_NAME}"
        "uapi --user=${TO_USER} Mysql create_user name=${DEST_DB_USER} password='<redacted>'"
        "uapi --user=${TO_USER} Mysql set_privileges_on_database user=${DEST_DB_USER} database=${DEST_DB_NAME} privileges=ALL%20PRIVILEGES"
        "mariadb '${DEST_DB_NAME}' < '${dump_file}'"
        "patch wp-config.php in ${DEST_DOCROOT} (DB_NAME/USER/PASSWORD/HOST)"
    )

    if [[ "$exec_mode" == "dry-run" ]]; then
        log_both "[DRY] DB migration plan:"
        for c in "${cmds[@]}"; do log_both "[DRY]   $c"; done
        return 0
    fi

    if ! mysqldump --single-transaction --quick --routines --triggers --events "$SRC_DB_NAME" > "$dump_file" 2>>"$LOG_FILE"; then
        log_err "mysqldump failed for $SRC_DB_NAME"
        return 1
    fi
    log_ok "dumped $SRC_DB_NAME -> $dump_file ($(du -sh "$dump_file" | awk '{print $1}'))"

    if ! uapi --user="$TO_USER" Mysql create_database name="$DEST_DB_NAME" >>"$LOG_FILE" 2>&1; then
        log_err "create_database $DEST_DB_NAME failed (see log)"; return 1
    fi
    if ! uapi --user="$TO_USER" Mysql create_user name="$DEST_DB_USER" password="$tmp_pass" >>"$LOG_FILE" 2>&1; then
        log_err "create_user $DEST_DB_USER failed"; return 1
    fi
    if ! uapi --user="$TO_USER" Mysql set_privileges_on_database user="$DEST_DB_USER" database="$DEST_DB_NAME" privileges="ALL PRIVILEGES" >>"$LOG_FILE" 2>&1; then
        log_err "grant privileges failed"; return 1
    fi
    # Confirm the generated password actually works — if cPanel stored a
    # different hash (the silent corruption we hit in v1.0.0), reset it now.
    if ! db_login_test "$DEST_DB_USER" "$tmp_pass" "localhost" "$DEST_DB_NAME"; then
        log_warn "DB login with generated password failed — resetting via set_password"
        if ! uapi --user="$TO_USER" Mysql set_password user="$DEST_DB_USER" password="$tmp_pass" >>"$LOG_FILE" 2>&1; then
            log_err "set_password also failed — check log"; return 1
        fi
        if ! db_login_test "$DEST_DB_USER" "$tmp_pass" "localhost" "$DEST_DB_NAME"; then
            log_err "DB login still fails after set_password"; return 1
        fi
        log_ok "DB login confirmed after password reset"
    else
        log_ok "DB login confirmed with generated password"
    fi
    if ! mariadb "$DEST_DB_NAME" < "$dump_file" 2>>"$LOG_FILE"; then
        log_err "import to $DEST_DB_NAME failed"; return 1
    fi
    log_ok "DB imported: $DEST_DB_NAME"

    local wpc="${DEST_DOCROOT}/wp-config.php"
    cp -a "$wpc" "${wpc}.bak.cpanel-migrate-addon" || { log_err "backup wp-config failed"; return 1; }
    # Match define('K', ...) AND define("K", ...), any whitespace, any quote mix.
    # The replacement normalizes to single quotes.
    sed -i -E \
        -e "s/define[[:space:]]*\([[:space:]]*['\"]DB_NAME['\"][[:space:]]*,[[:space:]]*['\"][^'\"]*['\"][[:space:]]*\)[[:space:]]*;/define('DB_NAME', '${DEST_DB_NAME}');/" \
        -e "s/define[[:space:]]*\([[:space:]]*['\"]DB_USER['\"][[:space:]]*,[[:space:]]*['\"][^'\"]*['\"][[:space:]]*\)[[:space:]]*;/define('DB_USER', '${DEST_DB_USER}');/" \
        -e "s|define[[:space:]]*\([[:space:]]*['\"]DB_PASSWORD['\"][[:space:]]*,[[:space:]]*['\"][^'\"]*['\"][[:space:]]*\)[[:space:]]*;|define('DB_PASSWORD', '${tmp_pass}');|" \
        "$wpc" || { log_err "sed on wp-config failed"; return 1; }
    # Sanity check: re-extract values and confirm they match
    local verify_name verify_user
    verify_name=$(php_extract_constant "$wpc" DB_NAME)
    verify_user=$(php_extract_constant "$wpc" DB_USER)
    if [[ "$verify_name" != "$DEST_DB_NAME" || "$verify_user" != "$DEST_DB_USER" ]]; then
        log_err "wp-config patch verification failed (got DB_NAME='$verify_name' DB_USER='$verify_user')"
        cp -a "${wpc}.bak.cpanel-migrate-addon" "$wpc"
        return 1
    fi
    log_ok "wp-config.php patched and verified (backup: ${wpc}.bak.cpanel-migrate-addon)"
    return 0
}

function create_dest_subdomain() {
    local exec_mode="$1"
    print_step "Create control subdomain on destination (${DEST_CONTROL_SUB})"

    if grep -qE "^${DEST_CONTROL_SUB}: ${TO_USER}\$" /etc/userdomains 2>/dev/null; then
        log_ok "subdomain ${DEST_CONTROL_SUB} already exists in ${TO_USER} — skipping (idempotent)"
        return 0
    fi

    local cmd="whmapi1 create_subdomain domain=${DEST_CONTROL_SUB} document_root=${DEST_DOCROOT_REL}"
    if [[ "$exec_mode" == "dry-run" ]]; then
        log_both "[DRY] $cmd"
        return 0
    fi
    whmapi1_must_succeed create_subdomain \
        domain="$DEST_CONTROL_SUB" \
        document_root="$DEST_DOCROOT_REL" \
        || { log_err "create_subdomain failed — check log"; return 1; }
    log_ok "subdomain ${DEST_CONTROL_SUB} created in ${TO_USER}"
    return 0
}

function create_dest_addon() {
    local exec_mode="$1"
    print_step "Park domain on destination vhost (${DOMAIN} -> ${DEST_CONTROL_SUB})"

    if grep -qE "^${DOMAIN}: ${TO_USER}\$" /etc/userdomains 2>/dev/null; then
        log_ok "addon ${DOMAIN} already registered on ${TO_USER} — skipping (idempotent)"
        return 0
    fi

    local cmd="whmapi1 create_parked_domain_for_user username=${TO_USER} domain=${DOMAIN} web_vhost_domain=${DEST_CONTROL_SUB}"
    if [[ "$exec_mode" == "dry-run" ]]; then
        log_both "[DRY] $cmd"
        return 0
    fi
    whmapi1_must_succeed create_parked_domain_for_user \
        username="$TO_USER" \
        domain="$DOMAIN" \
        web_vhost_domain="$DEST_CONTROL_SUB" \
        || { log_err "create_parked_domain_for_user failed — check log"; return 1; }
    log_ok "addon ${DOMAIN} registered on ${TO_USER}"
    return 0
}

function remove_source_addon() {
    local exec_mode="$1"
    print_step "Remove from source (${FROM_USER})"

    local c1="whmapi1 delete_domain domain=${DOMAIN}"
    local c2="whmapi1 delete_domain domain=${SOURCE_CONTROL_SUB}"

    if [[ "$exec_mode" == "dry-run" ]]; then
        log_both "[DRY] $c1"
        log_both "[DRY] $c2"
        return 0
    fi

    # Check that domain is still on source before attempting delete (idempotent)
    if grep -qE "^${DOMAIN}: ${FROM_USER}\$" /etc/userdomains 2>/dev/null; then
        whmapi1_must_succeed delete_domain domain="$DOMAIN" \
            || { log_err "delete_domain ${DOMAIN} failed"; return 1; }
        log_ok "removed addon ${DOMAIN} from ${FROM_USER}"
    else
        log_ok "${DOMAIN} already absent from source — skipping (idempotent)"
    fi

    if grep -qE "^${SOURCE_CONTROL_SUB}: ${FROM_USER}\$" /etc/userdomains 2>/dev/null; then
        if whmapi1_must_succeed delete_domain domain="$SOURCE_CONTROL_SUB"; then
            log_ok "removed control sub ${SOURCE_CONTROL_SUB}"
        else
            log_warn "delete_domain ${SOURCE_CONTROL_SUB} failed (non-fatal)"
        fi
    else
        log_ok "source control sub ${SOURCE_CONTROL_SUB} already gone"
    fi
    return 0
}

function set_dest_php_version() {
    local exec_mode="$1"
    print_step "Set PHP version on destination vhost (${SOURCE_PHP_VERSION})"

    if [[ "$SOURCE_PHP_VERSION" == "inherit" ]]; then
        log_ok "PHP version is 'inherit' — destination will use account default"
        return 0
    fi

    local cmd="whmapi1 php_set_vhost_versions vhost=${DEST_CONTROL_SUB} version=${SOURCE_PHP_VERSION}"
    if [[ "$exec_mode" == "dry-run" ]]; then
        log_both "[DRY] $cmd"
        return 0
    fi
    if whmapi1 --output=jsonpretty php_set_vhost_versions vhost="$DEST_CONTROL_SUB" version="$SOURCE_PHP_VERSION" >>"$LOG_FILE" 2>&1; then
        log_ok "PHP version set to ${SOURCE_PHP_VERSION} on ${DEST_CONTROL_SUB}"
        return 0
    fi
    log_err "php_set_vhost_versions failed — check log"
    return 1
}

function rebuild_httpd_conf() {
    local exec_mode="$1"
    print_step "Rebuild Apache/LSWS vhost config"
    local cmd="/scripts/rebuildhttpdconf"
    if [[ "$exec_mode" == "dry-run" ]]; then
        log_both "[DRY] $cmd"
        return 0
    fi
    if /scripts/rebuildhttpdconf >>"$LOG_FILE" 2>&1; then
        log_ok "httpd.conf rebuilt"
        return 0
    fi
    return 1
}

function cache_reload() {
    local exec_mode="$1"
    print_step "Cache + reload"

    local cmds=(
        "find ${DEST_DOCROOT}/wp-content/cache -mindepth 1 -delete 2>/dev/null || true"
        "/usr/local/lsws/bin/lswsctrl reload"
    )
    for c in "${cmds[@]}"; do
        if [[ "$exec_mode" == "dry-run" ]]; then
            log_both "[DRY] $c"
        else
            eval "$c" >>"$LOG_FILE" 2>&1 || log_warn "cmd returned non-zero: $c"
        fi
    done
    [[ "$exec_mode" == "dry-run" ]] || log_ok "cache cleared, LSWS reloaded"
    return 0
}

function autossl_reissue() {
    local exec_mode="$1"
    if [[ "$SKIP_SSL" == true ]]; then
        print_step "AutoSSL reissue — SKIPPED (--skip-ssl)"
        return 0
    fi
    print_step "AutoSSL reissue + wait for cert on ${DOMAIN}"

    if [[ "$exec_mode" == "dry-run" ]]; then
        log_both "[DRY] whmapi1 start_autossl_check_for_one_user username=${TO_USER}"
        log_both "[DRY] poll loop: check cert on :443 up to ${AUTOSSL_TIMEOUT_SEC:-120}s every ${AUTOSSL_POLL_SEC:-10}s"
        log_both "[DRY] on cert change: /usr/local/lsws/bin/lswsctrl reload"
        return 0
    fi

    # Trigger the check
    if ! whmapi1_must_succeed start_autossl_check_for_one_user username="$TO_USER"; then
        log_warn "start_autossl_check_for_one_user failed — falling back to legacy trigger"
        /usr/local/cpanel/bin/autossl_check --user="$TO_USER" >>"$LOG_FILE" 2>&1 || true
    fi

    # Snapshot pre-emission cert subject so we can detect change
    local pre_subject
    pre_subject=$(cert_subject_of "$DOMAIN")
    log_ok "pre-emission cert CN: ${pre_subject:-<none>}"

    local timeout="${AUTOSSL_TIMEOUT_SEC:-120}"
    local poll="${AUTOSSL_POLL_SEC:-10}"
    local elapsed=0
    local reloaded=false

    while (( elapsed < timeout )); do
        sleep "$poll"
        elapsed=$(( elapsed + poll ))

        local curr_subject
        curr_subject=$(cert_subject_of "$DOMAIN")
        if [[ -z "$curr_subject" ]]; then
            log_warn "(${elapsed}s) cert probe returned empty — tentando novamente"
            continue
        fi
        # The "good" cert has subject matching the domain or wildcard of it.
        if [[ "$curr_subject" == "$DOMAIN" || "$curr_subject" == "*.$DOMAIN" ]]; then
            log_ok "(${elapsed}s) cert emitted for ${DOMAIN} (CN=${curr_subject})"
            if [[ "$reloaded" != true ]]; then
                /usr/local/lsws/bin/lswsctrl reload >>"$LOG_FILE" 2>&1 || log_warn "lswsctrl reload failed"
                log_ok "LSWS reloaded to serve new cert"
                reloaded=true
                sleep 2
            fi
            return 0
        fi
        # Cert changed but still not the target one — try a reload mid-poll to force pickup.
        if [[ -n "$pre_subject" && "$curr_subject" != "$pre_subject" && "$reloaded" != true ]]; then
            log_ok "(${elapsed}s) cert subject changed to '${curr_subject}' — reloading LSWS"
            /usr/local/lsws/bin/lswsctrl reload >>"$LOG_FILE" 2>&1 || true
            reloaded=true
        fi
        log_both "   (${elapsed}s) cert still CN=${curr_subject} — waiting..."
    done

    log_warn "AutoSSL did not emit cert for ${DOMAIN} within ${timeout}s. Background job may still complete."
    log_warn "Check later: openssl s_client -servername ${DOMAIN} -connect ${DOMAIN}:443 2>/dev/null | openssl x509 -noout -subject"
    return 0
}

function cert_subject_of() {
    local host="$1"
    echo | timeout 5 openssl s_client -servername "$host" -connect "${host}:443" 2>/dev/null \
        | openssl x509 -noout -subject 2>/dev/null \
        | sed -n 's/.*CN *= *//p' \
        | head -1
}

function smoke_test() {
    # Robust smoke: GET with browser UA, parse HTTP code AND body signatures.
    # HEAD responses are often 403 on sites with strict .htaccess rules, so we
    # deliberately avoid them.
    local exec_mode="$1"
    print_step "Smoke test (GET + body analysis)"

    local urls=("http://${DOMAIN}/" "https://${DOMAIN}/")
    local fail=0
    for u in "${urls[@]}"; do
        if [[ "$exec_mode" == "dry-run" ]]; then
            log_both "[DRY] GET $u (UA=Mozilla/5.0 ...) — parse body for error signatures"
            continue
        fi
        local result; result=$(body_smoke "$u")
        local code size status note
        IFS='|' read -r code size status note <<< "$result"
        case "$status" in
            ok|redirect)
                log_ok "$u -> HTTP ${code} (${size}B, ${status})"
                ;;
            broken|empty|error)
                log_warn "$u -> HTTP ${code} (${size}B, ${status}${note:+: $note})"
                fail=1
                ;;
        esac
    done
    return $fail
}

function run_verify() {
    print_step "Post-migration verification (deep)"

    # Try to find the most recent DNS snapshot for this domain so we can
    # compare expected vs current records.
    local snap_candidate
    snap_candidate=$(ls -t "${STATE_DIR}/dns-backup/${DOMAIN}.db."*".json" 2>/dev/null | head -1)
    if [[ -n "$snap_candidate" && -f "$snap_candidate" ]]; then
        DNS_SNAPSHOT_JSON="$snap_candidate"
        log_ok "comparing against snapshot: $(basename "$snap_candidate")"
    fi

    # 1. Ownership
    local owner
    owner=$(grep -E "^${DOMAIN}: " /etc/userdomains | awk '{print $2}')
    if [[ "$owner" == "$TO_USER" ]]; then
        log_ok "ownership: ${owner} (expected)"
    else
        log_err "ownership: ${owner:-<nobody>} (expected: ${TO_USER})"
    fi

    # 2. Resolve control subdomain + docroot
    TO_MAIN_DOMAIN=$(awk -F': ' '$1=="main_domain"{print $2}' "/var/cpanel/userdata/${TO_USER}/main" | tr -d '"')
    local dest_sub="${DOMAIN}.${TO_MAIN_DOMAIN}"
    local docroot_now
    docroot_now=$(awk '/^documentroot:/{print $2}' "/var/cpanel/userdata/${TO_USER}/${dest_sub}" 2>/dev/null | head -1)
    log_ok "docroot: ${docroot_now:-<not found>}"

    # 3. WP deep check (if applicable)
    if [[ -n "$docroot_now" && -f "${docroot_now}/wp-config.php" ]]; then
        wp_siteurl_check "$docroot_now" "$DOMAIN"
    else
        log_ok "site type: static (no wp-config.php) — skipping DB/siteurl check"
    fi

    # 4. DNS sanity
    local result status message
    result=$(rdap_domain_status "$DOMAIN")
    status="${result%%|*}"; message="${result#*|}"
    log_ok "dns: ${status} (${message})"

    # 5. HTTP smoke
    DOMAIN_SAVE="$DOMAIN"
    smoke_test "verify"
    DOMAIN="$DOMAIN_SAVE"

    # 6. Cert SAN coverage
    local cn
    cn=$(cert_subject_of "$DOMAIN")
    log_ok "cert CN: ${cn:-<none>}"
    if cert_san_covers "$DOMAIN" "$DOMAIN"; then
        log_ok "cert covers apex ${DOMAIN}"
    else
        log_warn "cert does NOT cover apex ${DOMAIN} — AutoSSL may still be in progress"
    fi

    # 7. DNS record completeness (if snapshot available)
    if [[ -n "${DNS_SNAPSHOT_JSON:-}" && -f "$DNS_SNAPSHOT_JSON" ]]; then
        verify_dns_restore_completeness "apply" || \
            log_warn "DNS record diff detected — run apply again to reconcile"
    fi

    # 8. Exim routing sanity
    local mx mx_external
    mx=$(dig +short MX "$DOMAIN" @127.0.0.1 +time=3 +tries=1 2>/dev/null | head -1 | awk '{print $2}')
    mx="${mx%.}"
    if [[ -n "$mx" && "$mx" != "$DOMAIN" ]]; then mx_external=yes; else mx_external=no; fi
    if [[ "$mx_external" == "yes" ]]; then
        if grep -qxF "$DOMAIN" /etc/remotedomains 2>/dev/null; then
            log_ok "Exim routing: REMOTE (correct — MX is external)"
        else
            log_err "Exim routing: LOCAL but MX is external (${mx}) — mail will be intercepted!"
        fi
    fi
    return 0
}

function abort_with_rollback() {
    local code="$1"
    local reason="$2"
    log_err "ABORT (code=$code): ${reason}"
    log_err ""
    log_err "Preserved artifacts:"
    log_err "  snapshot: ${STATE_DIR}/${DOMAIN}.snapshot.json"
    log_err "  log:      ${LOG_FILE}"
    [[ -f "${STATE_DIR}/${DOMAIN}.dump.sql" ]] && log_err "  DB dump:  ${STATE_DIR}/${DOMAIN}.dump.sql"
    log_err ""
    log_err "Re-running ${SCRIPT_NAME} --apply is idempotent for steps 3-7 (check prior-state"
    log_err "guards were added in steps 6-7). If you need to fully roll back to source:"
    log_err ""
    log_err "  # 1) If addon was created on destination (step 7 completed):"
    log_err "  whmapi1 delete_domain domain=${DOMAIN}"
    log_err "  # 2) If control subdomain was created on destination (step 6 completed):"
    log_err "  whmapi1 delete_domain domain=${DEST_CONTROL_SUB}"
    log_err "  # 3) If you want to undo the source removal (steps 8+):"
    log_err "  whmapi1 create_subdomain domain=${SOURCE_CONTROL_SUB} document_root=${SOURCE_DOCROOT#/home/${FROM_USER}/}"
    log_err "  whmapi1 create_parked_domain_for_user username=${FROM_USER} domain=${DOMAIN} web_vhost_domain=${SOURCE_CONTROL_SUB}"
    log_err "  # 4) If DB was created on destination (step 5 completed):"
    [[ -n "${DEST_DB_NAME:-}" ]] && log_err "  uapi --user=${TO_USER} Mysql delete_database name=${DEST_DB_NAME}"
    [[ -n "${DEST_DB_USER:-}" ]] && log_err "  uapi --user=${TO_USER} Mysql delete_user name=${DEST_DB_USER}"
    exit "$code"
}

function run_or_echo() {
    local mode="$1"
    local cmd="$2"
    if [[ "$mode" == "dry-run" ]]; then
        log_both "[DRY] $cmd"
        return 0
    fi
    eval "$cmd" >>"$LOG_FILE" 2>&1
}

function print_header() {
    echo -e "${BLUE}${BOLD}===============================================${NC}"
    echo -e "${BLUE}${BOLD} $1${NC}"
    echo -e "${BLUE}${BOLD}===============================================${NC}"
}
function print_step()    { echo -e "${CYAN}▶ $1${NC}"; [[ -n "$LOG_FILE" ]] && echo "▶ $1" >>"$LOG_FILE"; }
function print_success() { echo -e "${GREEN}✅ $1${NC}"; [[ -n "$LOG_FILE" ]] && echo "✅ $1" >>"$LOG_FILE"; }
function print_error()   { echo -e "${RED}❌ $1${NC}" >&2; [[ -n "$LOG_FILE" ]] && echo "❌ $1" >>"$LOG_FILE"; }
function log_ok()        { [[ "$QUIET" == true ]] || echo -e "   ${GREEN}✓${NC} $1"; [[ -n "$LOG_FILE" ]] && echo "   ✓ $1" >>"$LOG_FILE"; }
function log_warn()      { echo -e "   ${YELLOW}⚠${NC} $1"; [[ -n "$LOG_FILE" ]] && echo "   ⚠ $1" >>"$LOG_FILE"; }
function log_err()       { echo -e "   ${RED}✗${NC} $1" >&2; [[ -n "$LOG_FILE" ]] && echo "   ✗ $1" >>"$LOG_FILE"; }
function log_both()      { [[ "$QUIET" == true ]] || echo "$1"; [[ -n "$LOG_FILE" ]] && echo "$1" >>"$LOG_FILE"; }

function reload_dns_server() {
    # Detect which authoritative DNS backend is running (PowerDNS with
    # launch=bind, or standalone BIND named) and reload it correctly.
    if systemctl is-active --quiet pdns 2>/dev/null; then
        pdns_control reload >/dev/null 2>&1 || true
        pdns_control purge >/dev/null 2>&1 || true
        return 0
    fi
    if systemctl is-active --quiet named 2>/dev/null; then
        if command -v rndc &>/dev/null; then
            rndc reload >/dev/null 2>&1 && return 0
        fi
        systemctl reload named >/dev/null 2>&1 && return 0
    fi
    log_warn "no active DNS backend detected — records may be stale until next cPanel cron"
    return 1
}

function verify_dns_restore_completeness() {
    # Post-restore sanity: compare the pre-migration JSON snapshot against the
    # live zone record-by-record. Retry any missing record up to 3 times.
    # Returns 0 if the zone is complete (all backup records present), else 1.
    local exec_mode="$1"
    [[ -z "${DNS_SNAPSHOT_JSON:-}" || ! -f "$DNS_SNAPSHOT_JSON" ]] && return 0

    print_step "Verify DNS restore completeness"
    if [[ "$exec_mode" == "dry-run" ]]; then
        log_both "[DRY] diff snapshot vs live zone, retry any missing record (up to 3x)"
        return 0
    fi

    local attempt still_missing
    for attempt in 1 2 3; do
        # Build two comparable line lists: "TYPE|name|value"
        local snap cur
        snap=$(jq -r '
            .data.zone[0].record[]
            | select(.type | IN("MX","CNAME","TXT","SRV","A","AAAA"))
            | [
                .type,
                (.name | sub("\\.$"; "") | ascii_downcase),
                (
                  if   .type == "MX"    then (.preference|tostring) + " " + (.exchange|sub("\\.$";""))
                  elif .type == "CNAME" then (.cname|sub("\\.$";""))
                  elif .type == "TXT"   then (.txtdata // "")
                  elif .type == "SRV"   then (.priority|tostring) + " " + (.weight|tostring) + " " + (.port|tostring) + " " + (.target|sub("\\.$";""))
                  elif .type == "A" or .type == "AAAA" then (.record // "")
                  else "" end
                )
              ]
            | @tsv
        ' "$DNS_SNAPSHOT_JSON" 2>/dev/null | sort -u)

        cur=$(whmapi1 --output=json dumpzone domain="$DOMAIN" 2>/dev/null | jq -r '
            .data.zone[0].record[]
            | select(.type | IN("MX","CNAME","TXT","SRV","A","AAAA"))
            | [
                .type,
                (.name | sub("\\.$"; "") | ascii_downcase),
                (
                  if   .type == "MX"    then (.preference|tostring) + " " + (.exchange|sub("\\.$";""))
                  elif .type == "CNAME" then (.cname|sub("\\.$";""))
                  elif .type == "TXT"   then (.txtdata // "")
                  elif .type == "SRV"   then (.priority|tostring) + " " + (.weight|tostring) + " " + (.port|tostring) + " " + (.target|sub("\\.$";""))
                  elif .type == "A" or .type == "AAAA" then (.record // "")
                  else "" end
                )
              ]
            | @tsv
        ' | sort -u)

        still_missing=$(comm -23 <(echo "$snap") <(echo "$cur"))
        if [[ -z "$still_missing" ]]; then
            log_ok "zone complete — all ${attempt}-pass records match backup"
            return 0
        fi

        local miss_count
        miss_count=$(echo "$still_missing" | grep -cE ".")
        log_warn "attempt ${attempt}: ${miss_count} records still missing, retrying..."
        while IFS=$'\t' read -r type name value; do
            [[ -z "$type" ]] && continue
            dns_add_from_tuple "$type" "$name" "$value"
        done <<< "$still_missing"
        reload_dns_server
        sleep 2
    done

    # After 3 tries, report what is still missing
    if [[ -n "$still_missing" ]]; then
        log_err "DNS restore incomplete after 3 attempts — still missing:"
        echo "$still_missing" | sed 's/^/     /' | head -15 | while read -r l; do log_err "$l"; done
        return 1
    fi
    return 0
}

function dns_add_from_tuple() {
    # Re-add a record given type / name / value tuple. Handles +→%2B encoding.
    local type="$1" name="$2" value="$3"
    # Restore trailing dot on FQDNs for whmapi1
    local n="$name"
    [[ "$n" != *"." ]] && n="${n}."
    case "$type" in
        MX)
            local pref="${value%% *}"
            local exch="${value#* }"
            whmapi1 --output=json addzonerecord zone="$DOMAIN" type=MX \
                name="$n" preference="$pref" exchange="${exch}." >/dev/null 2>&1
            ;;
        CNAME)
            whmapi1 --output=json addzonerecord zone="$DOMAIN" type=CNAME \
                name="$n" cname="${value}." >/dev/null 2>&1
            ;;
        TXT)
            local enc="${value//+/%2B}"
            whmapi1 --output=json addzonerecord zone="$DOMAIN" type=TXT \
                name="$n" txtdata="$enc" >/dev/null 2>&1
            ;;
        SRV)
            local pri wei por tgt
            pri=$(echo "$value" | awk '{print $1}')
            wei=$(echo "$value" | awk '{print $2}')
            por=$(echo "$value" | awk '{print $3}')
            tgt=$(echo "$value" | awk '{print $4}')
            whmapi1 --output=json addzonerecord zone="$DOMAIN" type=SRV \
                name="$n" priority="$pri" weight="$wei" port="$por" target="${tgt}." >/dev/null 2>&1
            ;;
        A|AAAA)
            whmapi1 --output=json addzonerecord zone="$DOMAIN" type="$type" \
                name="$n" address="$value" >/dev/null 2>&1
            ;;
    esac
}

function probe_external_mx() {
    # After configure_exim_routing, verify that the external MX actually
    # accepts SMTP banners. Non-fatal warning if it doesn't respond.
    local exec_mode="$1"
    [[ "$exec_mode" == "dry-run" ]] && { log_both "[DRY] SMTP banner probe on external MX (if any)"; return 0; }

    local mx
    mx=$(dig +short MX "$DOMAIN" @127.0.0.1 +time=3 +tries=1 2>/dev/null | head -1 | awk '{print $2}')
    mx="${mx%.}"
    [[ -z "$mx" || "$mx" == "$DOMAIN" ]] && return 0   # no external MX to probe

    print_step "SMTP banner probe on external MX (${mx})"
    local banner
    banner=$(timeout 6 bash -c "exec 3<>/dev/tcp/${mx}/25 && head -1 <&3 && exec 3>&-" 2>/dev/null)
    if [[ -n "$banner" ]]; then
        log_ok "MX ${mx} responded: ${banner:0:80}"
    else
        log_warn "MX ${mx} did not respond on TCP/25 (may be firewall on outbound 25; not necessarily broken)"
    fi
    return 0
}

function final_dns_reconciliation() {
    # Runs as the LAST step (after AutoSSL + smoke). Catches cases where a
    # later cPanel action (AutoSSL, SSL install, rebuild_httpd) wiped records
    # again. Idempotent re-run of restore + verify.
    local exec_mode="$1"
    [[ "$exec_mode" == "dry-run" ]] && { log_both "[DRY] final DNS reconciliation pass"; return 0; }
    [[ -z "${DNS_SNAPSHOT_JSON:-}" ]] && return 0
    print_step "Final DNS reconciliation (catches late cPanel regenerations)"
    restore_dns_custom_records "apply" >/dev/null 2>&1
    verify_dns_restore_completeness "apply"
    reload_dns_server
    return 0
}

function restore_dns_custom_records() {
    # After cPanel regenerates the zone during create_subdomain/create_parked,
    # replay every MX/CNAME/TXT/SRV/A/AAAA from the pre-migration JSON snapshot
    # via whmapi1 addzonerecord so M365/Google/custom records come back.
    local exec_mode="$1"
    print_step "Restore DNS custom records (post-migration)"

    if [[ -z "${DNS_SNAPSHOT_JSON:-}" || ! -f "${DNS_SNAPSHOT_JSON:-/nonexistent}" ]]; then
        log_warn "no DNS snapshot available — skipping restore"
        return 0
    fi

    if [[ "$exec_mode" == "dry-run" ]]; then
        local cnt
        cnt=$(jq '[.data.zone[0].record[] | select(.type | IN("MX","CNAME","TXT","SRV","A","AAAA"))] | length' "$DNS_SNAPSHOT_JSON" 2>/dev/null || echo 0)
        log_both "[DRY] would replay ${cnt} records from ${DNS_SNAPSHOT_JSON}"
        log_both "[DRY] would strip self-MX (where exchange == ${DOMAIN})"
        log_both "[DRY] would strip A records that collide with restored CNAMEs"
        log_both "[DRY] '+' in TXT values URL-encoded as %2B to survive whmapi1 decoding"
        return 0
    fi

    # Step 1: remove cPanel-injected self-MX (MX apex → apex itself)
    local self_mx_lines
    self_mx_lines=$(whmapi1 --output=json dumpzone domain="$DOMAIN" 2>/dev/null \
        | jq -r --arg d "$DOMAIN" '
            .data.zone[0].record[]
            | select(.type == "MX")
            | select((.exchange // "") == $d or (.exchange // "") == ($d + "."))
            | .Line
        ' | sort -rn)
    for L in $self_mx_lines; do
        whmapi1 --output=json removezonerecord zone="$DOMAIN" Line="$L" >/dev/null 2>&1 \
            && log_ok "stripped self-MX (line $L)"
    done

    # Step 2: collect CNAME targets from snapshot — A records on those names must go
    local cname_names
    cname_names=$(jq -r '.data.zone[0].record[] | select(.type=="CNAME") | .name' "$DNS_SNAPSHOT_JSON" 2>/dev/null | sort -u)
    if [[ -n "$cname_names" ]]; then
        local cur; cur=$(whmapi1 --output=json dumpzone domain="$DOMAIN" 2>/dev/null)
        while IFS= read -r cn; do
            [[ -z "$cn" ]] && continue
            local a_lines
            a_lines=$(echo "$cur" | jq -r --arg n "$cn" '
                .data.zone[0].record[]
                | select(.type == "A" and .name == $n)
                | .Line
            ' | sort -rn)
            for L in $a_lines; do
                whmapi1 --output=json removezonerecord zone="$DOMAIN" Line="$L" >/dev/null 2>&1 \
                    && log_ok "removed A on ${cn%.} (line $L) — will be CNAME"
            done
        done <<< "$cname_names"
    fi

    # Step 3: replay every record from the snapshot (skip SOA/NS — cPanel owns those)
    local replay
    replay=$(jq -c '
        .data.zone[0].record[]
        | select(.type | IN("MX","CNAME","TXT","SRV","A","AAAA"))
    ' "$DNS_SNAPSHOT_JSON" 2>/dev/null)

    local added=0 skipped=0 failed=0
    while IFS= read -r rec; do
        [[ -z "$rec" ]] && continue
        local type name
        type=$(echo "$rec" | jq -r '.type')
        name=$(echo "$rec" | jq -r '.name')
        case "$type" in
            MX)
                local pref exch
                pref=$(echo "$rec" | jq -r '.preference')
                exch=$(echo "$rec" | jq -r '.exchange')
                # Skip self-MX (already removed above; re-adding creates noise)
                [[ "$exch" == "$DOMAIN" || "$exch" == "${DOMAIN}." ]] && { skipped=$((skipped+1)); continue; }
                if dns_record_already_present MX "$name" "$exch"; then
                    skipped=$((skipped+1))
                else
                    whmapi1 --output=json addzonerecord zone="$DOMAIN" type=MX \
                        name="$name" preference="$pref" exchange="$exch" >/dev/null 2>&1 \
                        && { added=$((added+1)); log_ok "  + MX ${pref} ${exch}"; } \
                        || failed=$((failed+1))
                fi
                ;;
            CNAME)
                local target
                target=$(echo "$rec" | jq -r '.cname')
                if dns_record_already_present CNAME "$name" "$target"; then
                    skipped=$((skipped+1))
                else
                    whmapi1 --output=json addzonerecord zone="$DOMAIN" type=CNAME \
                        name="$name" cname="$target" >/dev/null 2>&1 \
                        && { added=$((added+1)); log_ok "  + CNAME ${name%.} -> ${target}"; } \
                        || failed=$((failed+1))
                fi
                ;;
            TXT)
                local val val_enc
                val=$(echo "$rec" | jq -r '.txtdata')
                val_enc="${val//+/%2B}"
                if dns_record_already_present TXT "$name" "$val"; then
                    skipped=$((skipped+1))
                else
                    whmapi1 --output=json addzonerecord zone="$DOMAIN" type=TXT \
                        name="$name" txtdata="$val_enc" >/dev/null 2>&1 \
                        && { added=$((added+1)); log_ok "  + TXT ${name%.} (${#val} chars)"; } \
                        || failed=$((failed+1))
                fi
                ;;
            SRV)
                local pri wei por tgt
                pri=$(echo "$rec" | jq -r '.priority')
                wei=$(echo "$rec" | jq -r '.weight')
                por=$(echo "$rec" | jq -r '.port')
                tgt=$(echo "$rec" | jq -r '.target')
                if dns_record_already_present SRV "$name" "$tgt"; then
                    skipped=$((skipped+1))
                else
                    whmapi1 --output=json addzonerecord zone="$DOMAIN" type=SRV \
                        name="$name" priority="$pri" weight="$wei" port="$por" target="$tgt" >/dev/null 2>&1 \
                        && { added=$((added+1)); log_ok "  + SRV ${name%.} -> ${tgt}"; } \
                        || failed=$((failed+1))
                fi
                ;;
            A|AAAA)
                local ip; ip=$(echo "$rec" | jq -r '.record')
                if dns_record_already_present "$type" "$name" "$ip"; then
                    skipped=$((skipped+1))
                else
                    whmapi1 --output=json addzonerecord zone="$DOMAIN" type="$type" \
                        name="$name" address="$ip" >/dev/null 2>&1 \
                        && { added=$((added+1)); log_ok "  + ${type} ${name%.} -> ${ip}"; } \
                        || failed=$((failed+1))
                fi
                ;;
        esac
    done <<< "$replay"

    log_ok "records replayed — added=${added} skipped=${skipped} failed=${failed}"

    # Step 4: strip mangled SPF (v=spf1 with collapsed '+' -> double spaces)
    local mangled
    mangled=$(whmapi1 --output=json dumpzone domain="$DOMAIN" 2>/dev/null | jq -r '
        .data.zone[0].record[]
        | select(.type == "TXT")
        | select((.txtdata // "") | test("^v=spf1"))
        | select((.txtdata // "") | test("\\+") | not)
        | select((.txtdata // "") | test("[[:space:]][[:space:]]"))
        | .Line
    ' | sort -rn)
    for L in $mangled; do
        whmapi1 --output=json removezonerecord zone="$DOMAIN" Line="$L" >/dev/null 2>&1 \
            && log_ok "stripped mangled SPF (line $L)"
    done
    return 0
}

function dns_record_already_present() {
    # Check whether the current live zone already has the given record.
    local type="$1" name="$2" value="$3"
    whmapi1 --output=json dumpzone domain="$DOMAIN" 2>/dev/null \
        | jq -e --arg t "$type" --arg n "$name" --arg v "$value" '
            .data.zone[0].record[]
            | select(.type == $t)
            | select(.name == $n or .name == ($n + "."))
            | select(
                (.exchange // "") == $v
                or (.cname // "") == $v
                or (.txtdata // "") == $v
                or (.record // "") == $v
                or (.target // "") == $v
              )
        ' >/dev/null 2>&1
}

function configure_exim_routing() {
    # If the domain's MX (post-restore) points to an external host (not the
    # apex itself), mark the domain as REMOTE in Exim so the local MTA does
    # not intercept mail destined for M365/Google/etc.
    local exec_mode="$1"
    print_step "Exim mail routing (local vs remote)"

    local mx
    mx=$(dig +short MX "$DOMAIN" @127.0.0.1 +time=3 +tries=1 2>/dev/null | head -1 | awk '{print $2}')
    if [[ -z "$mx" ]]; then
        log_warn "no MX resolved for ${DOMAIN} — leaving Exim routing untouched"
        return 0
    fi
    # Strip trailing dot
    mx="${mx%.}"

    local is_external=false
    # External if MX is NOT the apex itself AND NOT pointing to a subdomain of apex that resolves here
    if [[ "$mx" != "$DOMAIN" && "$mx" != "${DOMAIN}." ]]; then
        is_external=true
    fi

    if [[ "$is_external" == true ]]; then
        log_ok "MX points to '${mx}' (external) — domain must be REMOTE in Exim"
        if [[ "$exec_mode" == "dry-run" ]]; then
            log_both "[DRY] remove ${DOMAIN} from /etc/localdomains"
            log_both "[DRY] add ${DOMAIN} to /etc/remotedomains"
            log_both "[DRY] /scripts/buildeximconf + /scripts/restartsrv_exim"
            return 0
        fi
        sed -i "/^${DOMAIN//./\\.}$/d" /etc/localdomains 2>/dev/null
        grep -qxF "$DOMAIN" /etc/remotedomains 2>/dev/null || echo "$DOMAIN" >> /etc/remotedomains
        /scripts/buildeximconf >>"$LOG_FILE" 2>&1
        /scripts/restartsrv_exim >>"$LOG_FILE" 2>&1
        log_ok "Exim reconfigured: ${DOMAIN} marked as remote"
    else
        log_ok "MX points to apex (${mx}) — keeping Exim as LOCAL"
    fi
    return 0
}

function whmapi1_must_succeed() {
    # Runs `whmapi1 --output=json <func> <args...>`, tees the JSON into $LOG_FILE,
    # and returns 0 only if metadata.result == 1. Otherwise logs the reason and
    # returns non-zero.
    local func="$1"; shift
    local out
    out=$(whmapi1 --output=json "$func" "$@" 2>&1)
    echo "$out" >>"$LOG_FILE"
    local result
    result=$(echo "$out" | jq -r '.metadata.result // 0' 2>/dev/null)
    if [[ "$result" == "1" ]]; then
        return 0
    fi
    local reason
    reason=$(echo "$out" | jq -r '.metadata.reason // "unknown"' 2>/dev/null)
    log_err "whmapi1 ${func} returned result=${result}: ${reason}"
    return 1
}

function backup_dns_zone() {
    # Captures TWO artifacts per migration:
    #  - .db file (BIND raw text) — for human inspection / diff
    #  - .json file (whmapi1 dumpzone output) — AUTHORITATIVE source used by
    #    restore_dns_custom_records() to re-apply records post-migration.
    # cPanel regenerates the zone during create_subdomain/create_parked_domain_for_user,
    # destroying custom MX/CNAME/SRV/TXT. We re-insert them from this snapshot.
    local exec_mode="$1"
    print_step "Backup DNS zone for ${DOMAIN} (full JSON snapshot)"

    local zone_file="/var/named/${DOMAIN}.db"
    local backup_dir="${STATE_DIR}/dns-backup"
    local ts; ts=$(date +%Y%m%d-%H%M%S)
    DNS_SNAPSHOT_BASE="${backup_dir}/${DOMAIN}.db.${ts}"

    if [[ ! -f "$zone_file" ]]; then
        log_warn "zone file ${zone_file} not found — skipping DNS backup"
        DNS_SNAPSHOT_JSON=""
        return 0
    fi

    if [[ "$exec_mode" == "dry-run" ]]; then
        log_both "[DRY] mkdir -p ${backup_dir}"
        log_both "[DRY] cp -a ${zone_file} ${DNS_SNAPSHOT_BASE}"
        log_both "[DRY] whmapi1 dumpzone domain=${DOMAIN} > ${DNS_SNAPSHOT_BASE}.json"
        log_both "[DRY] snapshot will drive post-migration record restore"
        DNS_SNAPSHOT_JSON="${DNS_SNAPSHOT_BASE}.json"
        return 0
    fi

    mkdir -p "$backup_dir" || { log_err "cannot create dns backup dir"; return 1; }
    cp -a "$zone_file" "$DNS_SNAPSHOT_BASE" || { log_err "cp zone file failed"; return 1; }
    whmapi1 --output=json dumpzone domain="$DOMAIN" > "${DNS_SNAPSHOT_BASE}.json" 2>/dev/null
    DNS_SNAPSHOT_JSON="${DNS_SNAPSHOT_BASE}.json"
    local record_count
    record_count=$(jq '.data.zone[0].record | length' "$DNS_SNAPSHOT_JSON" 2>/dev/null || echo 0)
    log_ok "zone backup: $DNS_SNAPSHOT_BASE"
    log_ok "zone JSON:   $DNS_SNAPSHOT_JSON (${record_count} records)"
    return 0
}

function validate_input_safety() {
    # Hard-reject anything that is not a valid RFC-ish hostname / cPanel username.
    # Domain: letters, digits, dot, hyphen. 1-253 chars.
    if ! [[ "$DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,251}[a-zA-Z0-9])?$ ]]; then
        print_error "invalid --domain '$DOMAIN' (must be a valid hostname)"
        return 1
    fi
    # cPanel usernames: lowercase letters + digits, 1-16 chars, must start with a letter.
    if ! [[ "$FROM_USER" =~ ^[a-z][a-z0-9]{0,15}$ ]]; then
        print_error "invalid --from '$FROM_USER' (cPanel username must be lowercase, max 16 chars, start with letter)"
        return 1
    fi
    if ! [[ "$TO_USER" =~ ^[a-z][a-z0-9]{0,15}$ ]]; then
        print_error "invalid --to '$TO_USER' (cPanel username must be lowercase, max 16 chars, start with letter)"
        return 1
    fi
    return 0
}

function exit_on_missing_tools() {
    local missing=()
    for cmd in "$@"; do
        if ! command -v "$cmd" &>/dev/null; then missing+=("$cmd"); fi
    done
    if [[ ${#missing[@]} -gt 0 ]]; then
        printf "Error: required tool(s) not found: %s\n" "${missing[*]}" >&2
        exit 4
    fi
}

# ----------------------------------------------------------------------------
# v1.1.0 intelligence helpers
# ----------------------------------------------------------------------------

function safe_random_password() {
    # 32-char alphanumeric+underscore prefix — known-safe through URL-encoding
    # of cPanel UAPI. Avoids the silent-hash-mismatch we hit when base64 chars
    # (+, /, =) slipped through tr filters non-deterministically.
    echo "CpMigr_$(openssl rand -hex 16)"
}

function rdap_domain_status() {
    # Returns "active", "inactive", "nxdomain", or "unknown" and fills stdout
    # with a one-line explanation.
    local domain="$1"
    local json status
    # .br uses registro.br RDAP; other TLDs we use Cloudflare DoH which reveals
    # NXDOMAIN-like conditions via Status=3.
    if [[ "$domain" == *.br ]]; then
        json=$(curl -sS -m 8 "https://rdap.registro.br/domain/${domain}" 2>/dev/null || echo '{}')
        if echo "$json" | jq -e '.handle' >/dev/null 2>&1; then
            status=$(echo "$json" | jq -r '.status[]? // empty' 2>/dev/null | head -1)
            local exp
            exp=$(echo "$json" | jq -r '.events[]? | select(.eventAction=="expiration") | .eventDate' 2>/dev/null | head -1)
            if [[ "$status" == "inactive" ]]; then
                echo "inactive|expired ${exp:-?}"
                return 0
            fi
            echo "${status:-active}|registered, expires ${exp:-?}"
            return 0
        fi
        echo "nxdomain|not found in registro.br RDAP"
        return 0
    fi
    # Non-.br: Cloudflare DoH A record — Status 0 = OK, 3 = NXDOMAIN
    json=$(curl -sS -m 8 "https://cloudflare-dns.com/dns-query?name=${domain}&type=A" \
        -H "accept: application/dns-json" 2>/dev/null || echo '{}')
    local s
    s=$(echo "$json" | jq -r '.Status // -1' 2>/dev/null)
    case "$s" in
        0)  echo "active|resolves via Cloudflare DoH"; return 0 ;;
        3)  echo "nxdomain|NXDOMAIN via Cloudflare DoH"; return 0 ;;
        *)  echo "unknown|DoH returned Status=$s"; return 0 ;;
    esac
}

function check_domain_registration() {
    # Called during preflight. Returns 0 if domain resolves / 1 if strict-dns
    # and domain is inactive/nxdomain. Always logs.
    local domain="$1"
    print_step "DNS/registration sanity (${domain})"
    local result status message
    result=$(rdap_domain_status "$domain")
    status="${result%%|*}"
    message="${result#*|}"
    case "$status" in
        active)
            log_ok "domain status: ${status} (${message})"
            return 0
            ;;
        inactive|nxdomain)
            log_warn "domain status: ${status} (${message})"
            log_warn "AutoSSL will not be able to issue new certs until this is resolved"
            if [[ "$STRICT_DNS" == true ]]; then
                log_err "aborting due to --strict-dns"
                return 1
            fi
            return 0
            ;;
        *)
            log_warn "domain status: ${status} (${message}) — proceeding"
            return 0
            ;;
    esac
}

function detect_subdomain_children() {
    # Fill array SUBDOMAIN_CHILDREN with FQDN subdomains that live under $DOMAIN
    # within the SAME source account. cPanel refuses delete_domain on an addon
    # while any of its subdomains still exist — so we must handle them first.
    SUBDOMAIN_CHILDREN=()
    local ud_main="/var/cpanel/userdata/${FROM_USER}/main"
    [[ -f "$ud_main" ]] || return 0
    # sub_domains is a YAML-ish list. Pick entries ending with .DOMAIN
    local subs
    subs=$(awk '
        /^sub_domains:/    {insub=1; next}
        /^[a-zA-Z_]+:/     {insub=0}
        insub && /^[[:space:]]*-[[:space:]]*/ {
            gsub(/^[[:space:]]*-[[:space:]]*/, "")
            gsub(/"/, "")
            print
        }
    ' "$ud_main")
    while IFS= read -r sub; do
        [[ -z "$sub" ]] && continue
        # Skip the domain's own control subdomain (<DOMAIN>.<FROM_MAIN>)
        [[ "$sub" == "$SOURCE_CONTROL_SUB" ]] && continue
        # Match only real children of DOMAIN (e.g. lp.DOMAIN, api.DOMAIN)
        if [[ "$sub" == *".${DOMAIN}" ]]; then
            SUBDOMAIN_CHILDREN+=("$sub")
        fi
    done <<< "$subs"
}

function migrate_subdomain_child() {
    # Migrate a standalone subdomain (not an addon) between accounts.
    # Steps mirror the addon flow but there is no "park" operation: the sub's
    # hostname is created directly on the destination account after the parent
    # addon has moved, since cPanel needs the parent domain to already be owned
    # by the destination user.
    local sub="$1"
    local exec_mode="$2"
    log_both ""
    print_step "Migrate subdomain child: ${sub}"

    local sub_ud="/var/cpanel/userdata/${FROM_USER}/${sub}"
    if [[ ! -f "$sub_ud" ]]; then
        log_err "subdomain userdata not found: ${sub_ud}"
        return 1
    fi
    local src_docroot sub_php sub_relpath
    src_docroot=$(awk '/^documentroot:/{print $2}' "$sub_ud")
    sub_php=$(awk '/^phpversion:/{print $2}' "$sub_ud" | tr -d '"')
    if [[ -z "$src_docroot" || ! -d "$src_docroot" ]]; then
        log_err "could not resolve source docroot for ${sub}"
        return 1
    fi
    sub_relpath="${src_docroot#/home/${FROM_USER}/}"
    local dst_docroot="/home/${TO_USER}/${sub_relpath}"

    # Detect NESTED docroot — child lives INSIDE parent's docroot.
    # In that case, the rsync of the parent has already copied this directory.
    local nested=false
    if [[ "$src_docroot" == "${SOURCE_DOCROOT}/"* ]]; then
        nested=true
    fi

    log_ok "  src: ${src_docroot}"
    log_ok "  dst: ${dst_docroot}"
    log_ok "  php: ${sub_php:-inherit}"
    [[ "$nested" == true ]] && log_ok "  nested: YES (docroot lives inside parent — skipping redundant rsync)"

    # 1. Copy files (rsync) — unless nested (parent rsync already copied it)
    if [[ "$nested" == true ]]; then
        if [[ "$exec_mode" != "dry-run" ]]; then
            chown -R "${TO_USER}:${TO_USER}" "$dst_docroot" 2>/dev/null || true
        fi
    else
        local rsync_cmd="rsync -aHAX --delete-after --chown=${TO_USER}:${TO_USER} '${src_docroot}/' '${dst_docroot}/'"
        if [[ "$exec_mode" == "dry-run" ]]; then
            log_both "[DRY] mkdir -p '${dst_docroot}' && chown ${TO_USER}:${TO_USER} ..."
            log_both "[DRY] $rsync_cmd"
        else
            mkdir -p "$(dirname "$dst_docroot")" "$dst_docroot"
            chown -R "${TO_USER}:${TO_USER}" "$(dirname "$dst_docroot")"
            chmod 755 "$dst_docroot"
            eval "$rsync_cmd" >>"$LOG_FILE" 2>&1 || { log_err "rsync failed for ${sub}"; return 1; }
            log_ok "  rsync completed"
        fi
    fi

    # 2. DB migration if WP
    local sub_db_name="" sub_db_user="" sub_db_pass=""
    if [[ -f "${src_docroot}/wp-config.php" && "$SKIP_DB" != true ]]; then
        local src_db dst_db
        src_db=$(php_extract_constant "${src_docroot}/wp-config.php" DB_NAME)
        if [[ -n "$src_db" ]]; then
            dst_db=$(rename_with_prefix "$src_db" "$FROM_USER" "$TO_USER")
            local src_user dst_user
            src_user=$(php_extract_constant "${src_docroot}/wp-config.php" DB_USER)
            dst_user=$(rename_with_prefix "$src_user" "$FROM_USER" "$TO_USER")
            sub_db_name="$dst_db"
            sub_db_user="$dst_user"
            sub_db_pass=$(safe_random_password)

            local dump="${STATE_DIR}/${sub}.dump.sql"
            if [[ "$exec_mode" == "dry-run" ]]; then
                log_both "[DRY]   mariadb-dump '$src_db' > '$dump'"
                log_both "[DRY]   uapi Mysql create_database/create_user/grants (${dst_db}/${dst_user})"
                log_both "[DRY]   mariadb '$dst_db' < '$dump'"
                log_both "[DRY]   sed wp-config.php DB_* in ${dst_docroot}"
            else
                mariadb-dump --single-transaction --quick --routines --triggers --events "$src_db" > "$dump" 2>>"$LOG_FILE" \
                    || { log_err "dump failed for ${src_db}"; return 1; }
                uapi --user="$TO_USER" Mysql create_database name="$dst_db" >>"$LOG_FILE" 2>&1
                uapi --user="$TO_USER" Mysql create_user name="$dst_user" password="$sub_db_pass" >>"$LOG_FILE" 2>&1
                uapi --user="$TO_USER" Mysql set_privileges_on_database user="$dst_user" database="$dst_db" privileges="ALL PRIVILEGES" >>"$LOG_FILE" 2>&1
                mariadb "$dst_db" < "$dump" 2>>"$LOG_FILE" || { log_err "import failed for ${dst_db}"; return 1; }
                local wpc="${dst_docroot}/wp-config.php"
                cp -a "$wpc" "${wpc}.bak.cpanel-migrate-addon"
                sed -i -E \
                    -e "s/define[[:space:]]*\([[:space:]]*['\"]DB_NAME['\"][[:space:]]*,[[:space:]]*['\"][^'\"]*['\"][[:space:]]*\)[[:space:]]*;/define('DB_NAME', '${dst_db}');/" \
                    -e "s/define[[:space:]]*\([[:space:]]*['\"]DB_USER['\"][[:space:]]*,[[:space:]]*['\"][^'\"]*['\"][[:space:]]*\)[[:space:]]*;/define('DB_USER', '${dst_user}');/" \
                    -e "s|define[[:space:]]*\([[:space:]]*['\"]DB_PASSWORD['\"][[:space:]]*,[[:space:]]*['\"][^'\"]*['\"][[:space:]]*\)[[:space:]]*;|define('DB_PASSWORD', '${sub_db_pass}');|" \
                    "$wpc"
                log_ok "  DB migrated: ${dst_db}"
            fi
        fi
    fi

    # 3. Delete source subdomain (releases cPanel constraint on the parent)
    if [[ "$exec_mode" == "dry-run" ]]; then
        log_both "[DRY] whmapi1 delete_domain domain=${sub}"
    else
        whmapi1_must_succeed delete_domain domain="$sub" \
            || { log_err "delete_domain ${sub} on source failed"; return 1; }
        log_ok "  removed from source"
    fi

    # Stash info so we can create the subdomain on destination AFTER the parent addon is moved
    SUBDOMAIN_CHILDREN_TO_CREATE+=("${sub}|${sub_relpath}|${sub_php:-inherit}|${sub_db_name}|${sub_db_user}")
    return 0
}

function post_create_subdomain_children() {
    # After the parent addon has moved to $TO_USER, recreate each child sub
    # that we removed from source. By this point parent resolves on destination,
    # so cPanel allows the create_subdomain call.
    local exec_mode="$1"
    [[ ${#SUBDOMAIN_CHILDREN_TO_CREATE[@]} -eq 0 ]] && return 0
    print_step "Create subdomain children on destination"
    local entry sub relpath php
    for entry in "${SUBDOMAIN_CHILDREN_TO_CREATE[@]}"; do
        IFS='|' read -r sub relpath php _ _ <<< "$entry"
        if [[ "$exec_mode" == "dry-run" ]]; then
            log_both "[DRY] whmapi1 create_subdomain domain=${sub} document_root=${relpath}"
            [[ "$php" != "inherit" ]] && log_both "[DRY] whmapi1 php_set_vhost_versions vhost=${sub} version=${php}"
            continue
        fi
        whmapi1_must_succeed create_subdomain domain="$sub" document_root="$relpath" \
            || { log_warn "create_subdomain ${sub} failed — manual action needed"; continue; }
        if [[ "$php" != "inherit" ]]; then
            whmapi1_must_succeed php_set_vhost_versions vhost="$sub" version="$php" >/dev/null \
                || log_warn "php_set_vhost_versions failed for ${sub}"
        fi
        log_ok "  child ${sub} created on ${TO_USER}"
    done
    return 0
}

function body_smoke() {
    # GET the URL with a browser-like UA, check HTTP code AND body signatures.
    # Echoes a single line: "CODE|SIZE|STATUS|NOTE"
    #   STATUS is one of: ok | empty | broken | redirect | error
    local url="$1"
    local tmp
    tmp=$(mktemp)
    local code size rc
    code=$(curl -sS -o "$tmp" -m 20 -L -A "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126" \
        -w "%{http_code}" "$url" 2>/dev/null)
    rc=$?
    # On any curl error (SSL, DNS, timeout), force code=000 to avoid contamination
    if [[ $rc -ne 0 ]]; then code="000"; fi
    # Code must be exactly 3 digits; otherwise clamp
    if [[ ! "$code" =~ ^[0-9]{3}$ ]]; then code="000"; fi
    size=$(wc -c <"$tmp" 2>/dev/null || echo 0)
    local status="ok" note=""
    if [[ "$code" == "000" ]]; then
        status="error"; note="connection failed"
    elif [[ "$size" -lt 80 ]]; then
        status="empty"; note="body ${size}B — likely white screen"
    else
        local lower; lower=$(tr '[:upper:]' '[:lower:]' <"$tmp" | head -c 16384)
        local pat
        for pat in "${BODY_ERROR_PATTERNS[@]}"; do
            if [[ "$lower" == *"${pat}"* ]]; then
                status="broken"; note="body contains '${pat}'"
                break
            fi
        done
        if [[ "$status" == "ok" && ("$code" == "301" || "$code" == "302") ]]; then
            status="redirect"
        fi
    fi
    rm -f "$tmp"
    echo "${code}|${size}|${status}|${note}"
}

function cert_san_covers() {
    # Returns 0 if the apex domain is covered by the cert's SAN (subject + SAN)
    local host="$1"
    local target="${2:-$host}"
    local out
    out=$(echo | timeout 5 openssl s_client -servername "$host" -connect "${host}:443" 2>/dev/null \
        | openssl x509 -noout -subject -ext subjectAltName 2>/dev/null)
    if [[ -z "$out" ]]; then return 1; fi
    # match either CN = target, wildcard *.parent, or explicit SAN entry
    local parent="${target#*.}"
    grep -qE "CN ?= ?${target//./\\.}($|,)|DNS:${target//./\\.}($|,)|DNS:\*\.${parent//./\\.}($|,)" <<< "$out"
}

function wp_detect_prefix_and_dbcreds() {
    # Extract $table_prefix and DB creds from a wp-config. Sets:
    #   WP_TABLE_PREFIX, WP_DB_NAME, WP_DB_USER, WP_DB_PASS, WP_DB_HOST
    local wpc="$1"
    [[ -f "$wpc" ]] || return 1
    WP_TABLE_PREFIX=$(awk -F"['\"]" '/^\$table_prefix[[:space:]]*=/{print $2; exit}' "$wpc")
    [[ -z "$WP_TABLE_PREFIX" ]] && WP_TABLE_PREFIX="wp_"
    WP_DB_NAME=$(php_extract_constant "$wpc" DB_NAME)
    WP_DB_USER=$(php_extract_constant "$wpc" DB_USER)
    WP_DB_PASS=$(php_extract_constant "$wpc" DB_PASSWORD)
    WP_DB_HOST=$(php_extract_constant "$wpc" DB_HOST)
    WP_DB_HOST="${WP_DB_HOST:-localhost}"
    return 0
}

function db_host_health() {
    # Returns 0 if DB host resolves AND accepts TCP connections on 3306.
    # Special case: "localhost" or "127.0.0.1" — always healthy (UNIX socket).
    local host="${1:-localhost}"
    if [[ "$host" == "localhost" || "$host" == "127.0.0.1" ]]; then
        return 0
    fi
    # Check DNS resolution
    local ip
    ip=$(getent hosts "$host" 2>/dev/null | awk '{print $1; exit}')
    if [[ -z "$ip" ]]; then return 1; fi
    # Try TCP 3306 briefly
    timeout 3 bash -c "exec 3<>/dev/tcp/${host}/3306" 2>/dev/null && return 0
    return 1
}

function detect_email_accounts() {
    # Returns a count of mailboxes under /home/<user>/mail/<domain>/
    # Echoes the count. Zero means safe to migrate w/o email handling.
    local user="$1" domain="$2"
    local maildir="/home/${user}/mail/${domain}"
    [[ -d "$maildir" ]] || { echo 0; return 0; }
    # Mailboxes appear as subdirs of mail/<domain>/ with a cur/ or new/ directory
    find "$maildir" -maxdepth 2 -type d \( -name cur -o -name new \) 2>/dev/null \
        | awk -F/ '{print $(NF-1)}' | sort -u | wc -l
}

function db_login_test() {
    # Test a DB login using a defaults-file (bypasses the known MariaDB 10.11.16
    # MYSQL_PWD CLI bug and also mimics how PHP/mysqli connects).
    #   Args: user, password, host, database
    # Returns 0 on success.
    local u="$1" p="$2" h="${3:-localhost}" d="$4"
    local cnf; cnf=$(mktemp)
    chmod 600 "$cnf"
    cat >"$cnf" <<CNF
[client]
user=${u}
password=${p}
host=${h}
CNF
    local out rc
    out=$(mariadb --defaults-file="$cnf" "$d" -e "SELECT 1 AS ok" 2>&1)
    rc=$?
    rm -f "$cnf"
    if [[ $rc -eq 0 ]]; then return 0; fi
    return 1
}

function wp_siteurl_check() {
    # Given a destination docroot, confirm:
    #   1) DB login works with wp-config creds
    #   2) $table_prefix.options has siteurl matching the expected domain
    local docroot="$1"
    local expected_host="$2"
    wp_detect_prefix_and_dbcreds "${docroot}/wp-config.php" || return 1
    if ! db_login_test "$WP_DB_USER" "$WP_DB_PASS" "$WP_DB_HOST" "$WP_DB_NAME"; then
        log_err "DB login FAILED with wp-config credentials (user=${WP_DB_USER}, db=${WP_DB_NAME})"
        log_err "hint: set_password via 'uapi --user=${TO_USER} Mysql set_password user=${WP_DB_USER} password=<new>' and patch wp-config"
        return 1
    fi
    log_ok "DB login OK (user=${WP_DB_USER}, db=${WP_DB_NAME}, prefix=${WP_TABLE_PREFIX})"
    local cnf; cnf=$(mktemp); chmod 600 "$cnf"
    cat >"$cnf" <<CNF
[client]
user=${WP_DB_USER}
password=${WP_DB_PASS}
host=${WP_DB_HOST}
CNF
    local siteurl
    siteurl=$(mariadb --defaults-file="$cnf" -NBe \
        "SELECT option_value FROM \`${WP_TABLE_PREFIX}options\` WHERE option_name='siteurl' LIMIT 1" \
        "$WP_DB_NAME" 2>/dev/null)
    rm -f "$cnf"
    if [[ -z "$siteurl" ]]; then
        log_warn "could not read siteurl from ${WP_TABLE_PREFIX}options"
        return 1
    fi
    log_ok "WP siteurl: ${siteurl}"
    if [[ "$siteurl" == *"${expected_host}"* ]]; then
        return 0
    fi
    log_warn "siteurl '${siteurl}' does not contain expected host '${expected_host}'"
    return 1
}

function batch_run() {
    # Run the script once per non-empty, non-comment line in $BATCH_FILE.
    # Format: one domain per line, OR "domain,from,to" (the latter overrides).
    local exec_mode="$1"
    if [[ ! -f "$BATCH_FILE" ]]; then
        print_error "batch file not found: $BATCH_FILE"
        exit 2
    fi
    mkdir -p "$REPORT_DIR" "$LOG_DIR" "$STATE_DIR"
    local ts; ts=$(date +%Y%m%d-%H%M%S)
    local report="${REPORT_DIR}/batch-${ts}.md"
    {
        echo "# cpanel-migrate-addon batch report"
        echo ""
        echo "- date: $(date -Is)"
        echo "- mode: ${exec_mode}"
        echo "- from: ${FROM_USER}"
        echo "- to:   ${TO_USER}"
        echo "- file: ${BATCH_FILE}"
        echo ""
        echo "| domain | exit | duration | notes |"
        echo "|---|---|---|---|"
    } > "$report"
    print_header "${SCRIPT_NAME} v${VERSION} — BATCH ${exec_mode^^}"
    log_both "Report: ${report}"
    log_both ""
    local line total=0 passed=0 failed=0
    while IFS= read -r line || [[ -n "$line" ]]; do
        line="${line%%#*}"
        line="${line//$'\r'/}"
        line="${line## }"; line="${line%% }"
        [[ -z "$line" ]] && continue
        local d f t
        if [[ "$line" == *","* ]]; then
            IFS=',' read -r d f t <<< "$line"
            d="${d// /}"; f="${f// /}"; t="${t// /}"
            [[ -z "$f" ]] && f="$FROM_USER"
            [[ -z "$t" ]] && t="$TO_USER"
        else
            d="${line// /}"; f="$FROM_USER"; t="$TO_USER"
        fi
        total=$((total+1))
        print_step "[batch ${total}] ${d}  (${f:-<auto>} -> ${t})"
        # Build flags. --from is omitted when empty so child will auto-detect.
        local flags=("--domain=$d" "--to=$t" "--${exec_mode}")
        [[ -n "$f" ]]             && flags+=("--from=$f")
        [[ "$AUTO_YES" == true ]]  && flags+=(--yes)
        [[ "$WITH_SUBS" == true ]] && flags+=(--with-subs)
        [[ "$STRICT_DNS" == true ]] && flags+=(--strict-dns)
        [[ "$SKIP_DB" == true ]]   && flags+=(--skip-db)
        [[ "$SKIP_SSL" == true ]]  && flags+=(--skip-ssl)
        local t0; t0=$(date +%s)
        "${BASH_SOURCE[0]}" "${flags[@]}"
        local rc=$?
        local t1; t1=$(date +%s)
        local dur=$((t1-t0))
        local note=""
        if [[ $rc -eq 0 ]]; then
            passed=$((passed+1)); note="ok"
        else
            failed=$((failed+1)); note="FAILED (exit ${rc})"
        fi
        echo "| ${d} | ${rc} | ${dur}s | ${note} |" >> "$report"
        log_both ""
    done < "$BATCH_FILE"
    {
        echo ""
        echo "## Summary"
        echo "- total:  ${total}"
        echo "- passed: ${passed}"
        echo "- failed: ${failed}"
    } >> "$report"
    print_header "Batch complete — ${passed}/${total} passed"
    log_both "Report: ${report}"
    [[ $failed -eq 0 ]] && return 0 || return 5
}

SUBDOMAIN_CHILDREN=()
SUBDOMAIN_CHILDREN_TO_CREATE=()

if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
    main "$@"
    exit 0
fi