_common.sh

#!/usr/bin/env bash
# Shared utilities for DEOS scripts
# Source this file: source "$(dirname "${BASH_SOURCE[0]}")/_common.sh"

# Namerefs (`local -n`) and `mapfile` below require bash 4.3+. Fail with a clear prerequisite error
# rather than the cryptic syntax error an older bash would emit; macOS still ships bash 3.2.
if [[ -z "${BASH_VERSINFO:-}" ]] || (( BASH_VERSINFO[0] < 4 || (BASH_VERSINFO[0] == 4 && BASH_VERSINFO[1] < 3) )); then
    echo "[ERROR] DEOS scripts require bash 4.3 or newer, found ${BASH_VERSION:-unknown}" >&2
    exit 1
fi

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[1]:-${BASH_SOURCE[0]}}")" && pwd)"
PROJECT_ROOT="${DEOS_PROJECT_ROOT:-$(dirname "$SCRIPT_DIR")}"
TEMPLATE_DIR="$PROJECT_ROOT/template"
BIN_DIR="${DEOS_BINARY_DIR:-$PROJECT_ROOT/bin}"

# Colour only when stdout is a terminal and NO_COLOR is unset, so redirected step logs and CI output
# stay free of escape sequences. The compact-output mode replays those logs on failure.
if [[ -t 1 && -z "${NO_COLOR:-}" ]]; then
    RED='\033[0;31m'
    GREEN='\033[0;32m'
    YELLOW='\033[1;33m'
    BLUE='\033[0;34m'
    CYAN='\033[0;36m'
    NC='\033[0m'
else
    RED=''
    GREEN=''
    YELLOW=''
    BLUE=''
    CYAN=''
    NC=''
fi

DEOS_VERBOSE="${DEOS_VERBOSE:-0}"
DEOS_FAILURE_TAIL_LINES="${DEOS_FAILURE_TAIL_LINES:-80}"

log_info()    { echo -e "${BLUE}[INFO]${NC} $1"; }
log_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
log_warning() { echo -e "${YELLOW}[WARNING]${NC} $1"; }
log_error()   { echo -e "${RED}[ERROR]${NC} $1"; }

phase_banner() {
    echo -e "\n${CYAN}--- $1 ---${NC}\n"
}

add_path_if_dir() {
    local dir="$1"
    if [[ ! -d "$dir" ]]; then
        return 0
    fi
    case ":$PATH:" in
        *":$dir:"*) return 0 ;;
    esac
    export PATH="$dir:$PATH"
    log_info "Added $dir to PATH"
}

hydrate_local_tool_paths() {
    add_path_if_dir "$BIN_DIR"
    add_path_if_dir "$HOME/.cargo/bin"
}

# Print the SHA-256 of one file with whichever checksum tool the platform provides, so the
# macOS arm64 path (shasum) does not fail on a shared verifier that assumed GNU coreutils.
deos_sha256_file() {
    local file="$1"
    if command -v sha256sum >/dev/null 2>&1; then
        sha256sum "$file" | cut -d ' ' -f 1
    elif command -v shasum >/dev/null 2>&1; then
        shasum -a 256 "$file" | cut -d ' ' -f 1
    else
        log_error "Install sha256sum or shasum to verify downloaded artifacts"
        return 1
    fi
}

verify_deos_omni_node() {
    local node_path="${1:-$BIN_DIR/polkadot-omni-node-deos}"
    local receipt="$BIN_DIR/.deos-omni-node.json"
    require_commands jq cut
    [[ -f "$receipt" && -f "$BIN_DIR/.polkadot-sdk-release" && -x "$node_path" ]] || {
        log_error "Select a qualified Omni with DEOS_OMNI_NODE_PATH and DEOS_OMNI_NODE_SHA256 through 01-download-binaries.sh"
        return 1
    }
    local release selected upstream actual
    release="$(jq -er 'select(.schema_version == 1) | .sdk_release | select(type == "string")' "$receipt")" || return 1
    selected="$(jq -er '.selected_sha256 | select(type == "string")' "$receipt")" || return 1
    upstream="$(jq -er '.upstream_omni_sha256 | select(type == "string")' "$receipt")" || return 1
    [[ "$release" == "$(<"$BIN_DIR/.polkadot-sdk-release")" && "$selected" =~ ^[a-f0-9]{64}$ && "$upstream" =~ ^[a-f0-9]{64}$ && "$selected" != "$upstream" ]] || {
        log_error "Selected Omni receipt does not match the SDK bundle or identifies its unpatched upstream artifact"
        return 1
    }
    actual="$(deos_sha256_file "$node_path")" || return 1
    [[ "$actual" == "$selected" ]] || { log_error "Selected Omni checksum mismatch: $node_path"; return 1; }
    log_success "Selected Omni artifact verified: $node_path ($selected)"
}

activate_pinned_node() {
    local package_json="$PROJECT_ROOT/web-client/package.json"
    [[ -f "$package_json" ]] || { log_error "Node version authority not found: $package_json"; exit 1; }
    command -v node >/dev/null 2>&1 || { log_error "Node is required to read $package_json"; exit 1; }
    local expected actual
    expected="$(node -e 'const p=require(process.argv[1]); process.stdout.write(p.volta?.node ?? "")' "$package_json")"
    [[ -n "$expected" ]] || { log_error "web-client package.json volta.node is required"; exit 1; }
    actual="$(node --version 2>/dev/null || true)"
    actual="${actual#v}"
    if [[ "$actual" == "$expected" ]]; then
        return 0
    fi
    local nvm_dir="${NVM_DIR:-$HOME/.nvm}"
    if [[ -s "$nvm_dir/nvm.sh" ]]; then
        # shellcheck disable=SC1090
        source "$nvm_dir/nvm.sh"
        nvm install "$expected"
        nvm use "$expected" >/dev/null
    elif command -v fnm >/dev/null 2>&1; then
        eval "$(fnm env --shell bash)"
        fnm install "$expected"
        fnm use "$expected" >/dev/null
    else
        log_error "Node $expected is required and neither nvm nor fnm is available"
        exit 1
    fi
    actual="$(node --version)"
    actual="${actual#v}"
    [[ "$actual" == "$expected" ]] || { log_error "Unable to activate Node $expected"; exit 1; }
    log_info "Activated repository Node $expected"
}

require_directory() {
    local dir="$1"
    local label="$2"
    if [[ ! -d "$dir" ]]; then
        log_error "$label not found: $dir"
        exit 1
    fi
}

require_local_script() {
    local script_name="$1"
    local script_path="$SCRIPT_DIR/$script_name"
    if [[ ! -x "$script_path" ]]; then
        log_error "Script not found or not executable: $script_name"
        exit 1
    fi
}

require_commands() {
    local missing=()
    local cmd
    for cmd in "$@"; do
        if ! command -v "$cmd" >/dev/null 2>&1; then
            missing+=("$cmd")
        fi
    done
    if [[ ${#missing[@]} -gt 0 ]]; then
        log_error "Missing required commands: ${missing[*]}"
        exit 1
    fi
}

run_script_step() {
    local label="$1"
    local script_name="$2"
    shift 2

    require_local_script "$script_name"
    log_info "Running: $label ($script_name)"
    local start_time
    start_time=$(date +%s)
    "$SCRIPT_DIR/$script_name" "$@"
    local end_time
    end_time=$(date +%s)
    log_success "$label completed in $((end_time - start_time))s"
}

step_log_path() {
    local label="$1"
    local slug
    slug="$(printf '%s' "$label" | tr -cs '[:alnum:]' '-' | tr '[:upper:]' '[:lower:]')"
    mktemp "${TMPDIR:-/tmp}/deos-${slug}.XXXXXX.log"
}

report_step_failure() {
    local log_path="$1"
    log_error "Last ${DEOS_FAILURE_TAIL_LINES} output lines:"
    tail -n "$DEOS_FAILURE_TAIL_LINES" "$log_path" >&2 || true
    log_error "Full output retained at: $log_path"
}

run_shell_step() {
    local label="$1"
    local timeout_minutes="$2"
    local command="$3"

    log_info "Running: $label"
    if [[ "$DEOS_VERBOSE" == "1" ]]; then
        log_info "Command: $command"
    fi

    local start_time
    local end_time
    local status
    local log_path=""
    start_time=$(date +%s)
    if [[ "$DEOS_VERBOSE" == "1" ]]; then
        if [[ -n "$timeout_minutes" ]]; then
            timeout "${timeout_minutes}m" bash -c "$command" || status=$?
        else
            bash -c "$command" || status=$?
        fi
    else
        log_path="$(step_log_path "$label")"
        if [[ -n "$timeout_minutes" ]]; then
            timeout "${timeout_minutes}m" bash -c "$command" >"$log_path" 2>&1 || status=$?
        else
            bash -c "$command" >"$log_path" 2>&1 || status=$?
        fi
    fi
    status="${status:-0}"
    end_time=$(date +%s)

    if [[ "$status" -ne 0 ]]; then
        log_error "$label failed with status $status after $((end_time - start_time))s"
        if [[ -n "$log_path" ]]; then
            report_step_failure "$log_path"
        fi
        return "$status"
    fi
    if [[ -n "$log_path" ]]; then
        rm -f "$log_path"
    fi
    log_success "$label completed in $((end_time - start_time))s"
}

run_command_step() {
    local label="$1"
    local timeout_minutes="$2"
    shift 2

    log_info "Running: $label"

    local start_time
    local end_time
    local status
    local log_path=""
    start_time=$(date +%s)
    if [[ "$DEOS_VERBOSE" == "1" ]]; then
        if [[ -n "$timeout_minutes" ]]; then
            timeout "${timeout_minutes}m" "$@" || status=$?
        else
            "$@" || status=$?
        fi
    else
        log_path="$(step_log_path "$label")"
        if [[ -n "$timeout_minutes" ]]; then
            timeout "${timeout_minutes}m" "$@" >"$log_path" 2>&1 || status=$?
        else
            "$@" >"$log_path" 2>&1 || status=$?
        fi
    fi
    status="${status:-0}"
    end_time=$(date +%s)

    if [[ "$status" -ne 0 ]]; then
        log_error "$label failed with status $status after $((end_time - start_time))s"
        if [[ -n "$log_path" ]]; then
            report_step_failure "$log_path"
        fi
        return "$status"
    fi
    if [[ -n "$log_path" ]]; then
        rm -f "$log_path"
    fi
    log_success "$label completed in $((end_time - start_time))s"
}

start_background_script() {
    local label="$1"
    local script_name="$2"
    local log_path="$3"
    local pid_var="$4"
    local -n pid_ref="$pid_var"

    require_local_script "$script_name"
    log_info "Starting $label in background"
    log_info "Log file: $log_path"
    "$SCRIPT_DIR/$script_name" >"$log_path" 2>&1 &
    pid_ref="$!"
    log_success "$label started with PID $pid_ref"
}

start_background_command() {
    local label="$1"
    local workdir="$2"
    local command="$3"
    local log_path="$4"
    local pid_var="$5"
    local -n pid_ref="$pid_var"

    require_directory "$workdir" "$label working directory"
    log_info "Starting $label in background"
    log_info "Working directory: $workdir"
    log_info "Command: $command"
    log_info "Log file: $log_path"
    (
        cd "$workdir"
        bash -c "$command"
    ) >"$log_path" 2>&1 &
    pid_ref="$!"
    log_success "$label started with PID $pid_ref"
}

wait_for_chain_rpc() {
    local http_uri="$1"
    local timeout_sec="$2"
    local label="$3"
    local pid="${4:-}"
    local log_path="${5:-}"
    local deadline=$((SECONDS + timeout_sec))

    while (( SECONDS < deadline )); do
        if curl -sS \
            -H 'Content-Type: application/json' \
            -d '{"id":1,"jsonrpc":"2.0","method":"chain_getHeader","params":[]}' \
            "$http_uri" >/dev/null 2>&1; then
            log_success "$label is reachable at $http_uri"
            return 0
        fi

        if [[ -n "$pid" ]] && ! kill -0 "$pid" >/dev/null 2>&1; then
            log_error "$label producer exited before RPC became ready"
            if [[ -n "$log_path" ]]; then
                log_info "Check log: $log_path"
            fi
            return 1
        fi

        sleep 2
    done

    log_error "Timed out waiting for $label at $http_uri (timeout=${timeout_sec}s)"
    if [[ -n "$log_path" ]]; then
        log_info "Check log: $log_path"
    fi
    return 1
}

wait_for_http() {
    local http_uri="$1"
    local timeout_sec="$2"
    local label="$3"
    local pid="${4:-}"
    local log_path="${5:-}"
    local deadline=$((SECONDS + timeout_sec))

    while (( SECONDS < deadline )); do
        if curl -fsS "$http_uri" >/dev/null 2>&1; then
            log_success "$label is reachable at $http_uri"
            return 0
        fi

        if [[ -n "$pid" ]] && ! kill -0 "$pid" >/dev/null 2>&1; then
            log_error "$label producer exited before HTTP became ready"
            if [[ -n "$log_path" ]]; then
                log_info "Check log: $log_path"
            fi
            return 1
        fi

        sleep 2
    done

    log_error "Timed out waiting for $label at $http_uri (timeout=${timeout_sec}s)"
    if [[ -n "$log_path" ]]; then
        log_info "Check log: $log_path"
    fi
    return 1
}

# Signals a process and every descendant, deepest first. `start_background_command` runs its work
# inside a subshell, so the recorded PID is only the ancestor: signalling it alone leaves the actual
# node or dev-server grandchild orphaned and holding its port.
kill_process_tree() {
    local pid="$1"
    local signal="${2:-TERM}"
    local child
    while IFS= read -r child; do
        [[ -n "$child" ]] && kill_process_tree "$child" "$signal"
    done < <(pgrep -P "$pid" 2>/dev/null || true)
    kill -"$signal" "$pid" >/dev/null 2>&1 || true
}

stop_background_process() {
    local pid="${1:-}"
    local keep_running="${2:-0}"
    local log_path="${3:-}"
    local label="${4:-process}"

    if [[ -z "$pid" ]]; then
        return 0
    fi

    if [[ "$keep_running" == "1" ]]; then
        log_warning "KEEP_NETWORK=1, leaving $label running (PID: $pid)"
        if [[ -n "$log_path" ]]; then
            log_info "Log file: $log_path"
        fi
        return 0
    fi

    if kill -0 "$pid" >/dev/null 2>&1; then
        log_info "Stopping $label (PID: $pid)"
        kill_process_tree "$pid" TERM
        for _ in {1..10}; do
            if ! kill -0 "$pid" >/dev/null 2>&1; then
                break
            fi
            sleep 1
        done
        if kill -0 "$pid" >/dev/null 2>&1; then
            log_warning "$label did not stop gracefully, sending SIGKILL"
            kill_process_tree "$pid" KILL
        fi
        log_success "$label stopped"
    fi
}