install.sh

#!/bin/bash
set -euo pipefail

# OpenRappter Installer for macOS and Linux
# Usage: curl -fsSL https://kody-w.github.io/openrappter/install.sh | bash

# Prevent sharp from trying to download global libvips (causes build failures in CI/Docker)
export SHARP_IGNORE_GLOBAL_LIBVIPS=1

BOLD='\033[1m'
ACCENT='\033[38;2;16;185;129m'       # green-bright  #10b981
# shellcheck disable=SC2034
ACCENT_BRIGHT='\033[38;2;52;211;153m' # lighter green #34d399
INFO='\033[38;2;136;146;176m'        # text-secondary #8892b0
SUCCESS='\033[38;2;0;229;204m'       # cyan-bright   #00e5cc
WARN='\033[38;2;255;176;32m'         # amber
ERROR='\033[38;2;230;57;70m'         # coral-mid     #e63946
MUTED='\033[38;2;90;100;128m'        # text-muted    #5a6480
NC='\033[0m' # No Color

DEFAULT_TAGLINE="AI agents powered by your existing GitHub Copilot subscription."

ORIGINAL_PATH="${PATH:-}"

TMPFILES=()
cleanup_tmpfiles() {
    local f
    for f in "${TMPFILES[@]:-}"; do
        rm -rf "$f" 2>/dev/null || true
    done
}
trap cleanup_tmpfiles EXIT

mktempfile() {
    local f
    f="$(mktemp)"
    TMPFILES+=("$f")
    echo "$f"
}

DOWNLOADER=""
detect_downloader() {
    if command -v curl &> /dev/null; then
        DOWNLOADER="curl"
        return 0
    fi
    if command -v wget &> /dev/null; then
        DOWNLOADER="wget"
        return 0
    fi
    ui_error "Missing downloader (curl or wget required)"
    exit 1
}

download_file() {
    local url="$1"
    local output="$2"
    if [[ -z "$DOWNLOADER" ]]; then
        detect_downloader
    fi
    if [[ "$DOWNLOADER" == "curl" ]]; then
        curl -fsSL --proto '=https' --tlsv1.2 --retry 3 --retry-delay 1 --retry-connrefused -o "$output" "$url"
        return
    fi
    wget -q --https-only --secure-protocol=TLSv1_2 --tries=3 --timeout=20 -O "$output" "$url"
}

run_remote_bash() {
    local url="$1"
    local tmp
    tmp="$(mktempfile)"
    download_file "$url" "$tmp"
    /bin/bash "$tmp"
}

# ── Retry wrapper for network operations ────────────────────
retry() {
    local max_attempts="$1"
    local delay="$2"
    shift 2
    local attempt=1
    while true; do
        if "$@"; then
            return 0
        fi
        if [[ "$attempt" -ge "$max_attempts" ]]; then
            return 1
        fi
        ui_info "Retrying ($attempt/$max_attempts) in ${delay}s..."
        sleep "$delay"
        ((attempt++))
        delay=$((delay * 2 > 30 ? 30 : delay * 2))
    done
}

# ── Gum (fancy terminal UI) ────────────────────────────────
GUM_VERSION="${OPENRAPPTER_GUM_VERSION:-0.17.0}"
GUM=""
GUM_STATUS="skipped"
GUM_REASON=""

gum_is_tty() {
    if [[ -n "${NO_COLOR:-}" ]]; then
        return 1
    fi
    if [[ "${TERM:-dumb}" == "dumb" ]]; then
        return 1
    fi
    if [[ -t 2 || -t 1 ]]; then
        return 0
    fi
    if [[ -r /dev/tty && -w /dev/tty ]]; then
        return 0
    fi
    return 1
}

gum_detect_os() {
    case "$(uname -s 2>/dev/null || true)" in
        Darwin) echo "Darwin" ;;
        Linux) echo "Linux" ;;
        *) echo "unsupported" ;;
    esac
}

gum_detect_arch() {
    case "$(uname -m 2>/dev/null || true)" in
        x86_64|amd64) echo "x86_64" ;;
        arm64|aarch64) echo "arm64" ;;
        i386|i686) echo "i386" ;;
        armv7l|armv7) echo "armv7" ;;
        armv6l|armv6) echo "armv6" ;;
        *) echo "unknown" ;;
    esac
}

verify_sha256sum_file() {
    local checksums="$1"
    if command -v sha256sum >/dev/null 2>&1; then
        sha256sum --ignore-missing -c "$checksums" >/dev/null 2>&1
        return $?
    fi
    if command -v shasum >/dev/null 2>&1; then
        shasum -a 256 --ignore-missing -c "$checksums" >/dev/null 2>&1
        return $?
    fi
    return 1
}

bootstrap_gum_temp() {
    GUM=""
    GUM_STATUS="skipped"
    GUM_REASON=""

    case "$OPENRAPPTER_USE_GUM" in
        0|false|False|FALSE|off|OFF|no|NO)
            GUM_REASON="disabled via OPENRAPPTER_USE_GUM"
            return 1
            ;;
    esac

    if ! gum_is_tty; then
        GUM_REASON="not a TTY"
        return 1
    fi

    if command -v gum >/dev/null 2>&1; then
        GUM="gum"
        GUM_STATUS="found"
        GUM_REASON="already installed"
        return 0
    fi

    if [[ "$OPENRAPPTER_USE_GUM" != "1" && "$OPENRAPPTER_USE_GUM" != "true" && "$OPENRAPPTER_USE_GUM" != "TRUE" ]]; then
        if [[ "$OPENRAPPTER_USE_GUM" != "auto" ]]; then
            GUM_REASON="invalid OPENRAPPTER_USE_GUM value: $OPENRAPPTER_USE_GUM"
            return 1
        fi
    fi

    if ! command -v tar >/dev/null 2>&1; then
        GUM_REASON="tar not found"
        return 1
    fi

    local os arch asset base gum_tmpdir gum_path
    os="$(gum_detect_os)"
    arch="$(gum_detect_arch)"
    if [[ "$os" == "unsupported" || "$arch" == "unknown" ]]; then
        GUM_REASON="unsupported os/arch ($os/$arch)"
        return 1
    fi

    asset="gum_${GUM_VERSION}_${os}_${arch}.tar.gz"
    base="https://github.com/charmbracelet/gum/releases/download/v${GUM_VERSION}"

    gum_tmpdir="$(mktemp -d)"
    TMPFILES+=("$gum_tmpdir")

    if ! download_file "${base}/${asset}" "$gum_tmpdir/$asset"; then
        GUM_REASON="download failed"
        return 1
    fi

    if ! download_file "${base}/checksums.txt" "$gum_tmpdir/checksums.txt"; then
        GUM_REASON="checksum unavailable or failed"
        return 1
    fi

    if ! (cd "$gum_tmpdir" && verify_sha256sum_file "checksums.txt"); then
        GUM_REASON="checksum unavailable or failed"
        return 1
    fi

    if ! tar -xzf "$gum_tmpdir/$asset" -C "$gum_tmpdir" >/dev/null 2>&1; then
        GUM_REASON="extract failed"
        return 1
    fi

    gum_path="$(find "$gum_tmpdir" -type f -name gum 2>/dev/null | head -n1 || true)"
    if [[ -z "$gum_path" ]]; then
        GUM_REASON="gum binary missing after extract"
        return 1
    fi

    chmod +x "$gum_path" >/dev/null 2>&1 || true
    if [[ ! -x "$gum_path" ]]; then
        GUM_REASON="gum binary is not executable"
        return 1
    fi

    GUM="$gum_path"
    GUM_STATUS="installed"
    GUM_REASON="temp, verified"
    return 0
}

print_gum_status() {
    case "$GUM_STATUS" in
        found)
            ui_success "gum available (${GUM_REASON})"
            ;;
        installed)
            ui_success "gum bootstrapped (${GUM_REASON}, v${GUM_VERSION})"
            ;;
        *)
            if [[ -n "$GUM_REASON" ]]; then
                ui_info "gum skipped (${GUM_REASON})"
            fi
            ;;
    esac
}

# ── UI Functions ────────────────────────────────────────────
print_installer_banner() {
    if [[ -n "$GUM" ]]; then
        local title tagline hint card
        title="$("$GUM" style --foreground "#10b981" --bold "🦖 OpenRappter Installer")"
        tagline="$("$GUM" style --foreground "#8892b0" "$TAGLINE")"
        hint="$("$GUM" style --foreground "#5a6480" "modern installer mode")"
        card="$(printf '%s\n%s\n%s' "$title" "$tagline" "$hint")"
        "$GUM" style --border rounded --border-foreground "#10b981" --padding "1 2" "$card"
        echo ""
        return
    fi

    echo -e "${ACCENT}${BOLD}"
    echo "  🦖 OpenRappter Installer"
    echo -e "${NC}${INFO}  ${TAGLINE}${NC}"
    echo ""
}

detect_os_or_die() {
    OS="unknown"
    if [[ "$OSTYPE" == "darwin"* ]]; then
        OS="macos"
    elif [[ "$OSTYPE" == "linux-gnu"* ]] || [[ -n "${WSL_DISTRO_NAME:-}" ]]; then
        OS="linux"
    fi

    if [[ "$OS" == "unknown" ]]; then
        ui_error "Unsupported operating system"
        echo "This installer supports macOS and Linux (including WSL)."
        exit 1
    fi

    ui_success "Detected: $OS"
}

detect_arch() {
    case "$(uname -m 2>/dev/null || true)" in
        x86_64|amd64) echo "x64" ;;
        arm64|aarch64) echo "arm64" ;;
        *) uname -m ;;
    esac
}

ui_info() {
    local msg="$*"
    if [[ -n "$GUM" ]]; then
        "$GUM" log --level info "$msg"
    else
        echo -e "${MUTED}·${NC} ${msg}"
    fi
}

ui_warn() {
    local msg="$*"
    if [[ -n "$GUM" ]]; then
        "$GUM" log --level warn "$msg"
    else
        echo -e "${WARN}!${NC} ${msg}"
    fi
}

ui_success() {
    local msg="$*"
    if [[ -n "$GUM" ]]; then
        local mark
        mark="$("$GUM" style --foreground "#00e5cc" --bold "✓")"
        echo "${mark} ${msg}"
    else
        echo -e "${SUCCESS}✓${NC} ${msg}"
    fi
}

ui_error() {
    local msg="$*"
    if [[ -n "$GUM" ]]; then
        "$GUM" log --level error "$msg"
    else
        echo -e "${ERROR}✗${NC} ${msg}"
    fi
}

INSTALL_STAGE_TOTAL=4
INSTALL_STAGE_CURRENT=0

ui_section() {
    local title="$1"
    if [[ -n "$GUM" ]]; then
        "$GUM" style --bold --foreground "#10b981" --padding "1 0" "$title"
    else
        echo ""
        echo -e "${ACCENT}${BOLD}${title}${NC}"
    fi
}

ui_stage() {
    local title="$1"
    INSTALL_STAGE_CURRENT=$((INSTALL_STAGE_CURRENT + 1))
    ui_section "[${INSTALL_STAGE_CURRENT}/${INSTALL_STAGE_TOTAL}] ${title}"
}

ui_kv() {
    local key="$1"
    local value="$2"
    if [[ -n "$GUM" ]]; then
        local key_part value_part
        key_part="$("$GUM" style --foreground "#5a6480" --width 20 "$key")"
        value_part="$("$GUM" style --bold "$value")"
        "$GUM" join --horizontal "$key_part" "$value_part"
    else
        echo -e "${MUTED}${key}:${NC} ${value}"
    fi
}

ui_panel() {
    local content="$1"
    if [[ -n "$GUM" ]]; then
        "$GUM" style --border rounded --border-foreground "#5a6480" --padding "0 1" "$content"
    else
        echo "$content"
    fi
}

ui_celebrate() {
    local msg="$1"
    if [[ -n "$GUM" ]]; then
        "$GUM" style --bold --foreground "#00e5cc" "$msg"
    else
        echo -e "${SUCCESS}${BOLD}${msg}${NC}"
    fi
}

# Numpad-friendly menu: type a number to choose (no arrow keys needed)
# Usage: ui_choose "Header text" "Option A" "Option B" ...
# Returns: selected option text on stdout
# Supports gum as visual upgrade, falls back to pure bash numpad input
ui_choose() {
    local header="$1"
    shift
    local options=("$@")
    local count=${#options[@]}

    if [[ "$count" -eq 0 ]]; then
        return 1
    fi

    # Single option — auto-select
    if [[ "$count" -eq 1 ]]; then
        echo "${options[0]}"
        return 0
    fi

    # Display header and numbered options
    echo "" >&2
    echo -e "${ACCENT}${BOLD}${header}${NC}" >&2
    echo "" >&2
    for i in "${!options[@]}"; do
        local num=$((i + 1))
        echo -e "  ${CYAN}${BOLD}${num}${NC}  ${options[$i]}" >&2
    done
    echo "" >&2

    # Read numpad input
    while true; do
        echo -n -e "${MUTED}Enter number [1-${count}]:${NC} " >&2
        local input
        read -r input </dev/tty 2>/dev/null || read -r input
        # Strip whitespace
        input="${input// /}"
        if [[ "$input" =~ ^[0-9]+$ ]] && (( input >= 1 && input <= count )); then
            echo "${options[$((input - 1))]}"
            return 0
        fi
        echo -e "${WARN}  Please enter a number between 1 and ${count}${NC}" >&2
    done
}

is_shell_function() {
    local name="${1:-}"
    [[ -n "$name" ]] && declare -F "$name" >/dev/null 2>&1
}

run_with_spinner() {
    local title="$1"
    shift

    if [[ -n "$GUM" ]] && gum_is_tty && ! is_shell_function "${1:-}"; then
        "$GUM" spin --spinner dot --title "$title" -- "$@"
        return $?
    fi

    "$@"
}

run_quiet_step() {
    local title="$1"
    shift

    if [[ "$VERBOSE" == "1" ]]; then
        run_with_spinner "$title" "$@"
        return $?
    fi

    local log
    log="$(mktempfile)"

    if [[ -n "$GUM" ]] && gum_is_tty && ! is_shell_function "${1:-}"; then
        local cmd_quoted=""
        local log_quoted=""
        printf -v cmd_quoted '%q ' "$@"
        printf -v log_quoted '%q' "$log"
        if run_with_spinner "$title" bash -c "${cmd_quoted}>${log_quoted} 2>&1"; then
            return 0
        fi
    else
        if "$@" >"$log" 2>&1; then
            return 0
        fi
    fi

    ui_error "${title} failed — re-run with --verbose for details"
    if [[ -s "$log" ]]; then
        tail -n 80 "$log" >&2 || true
    fi
    return 1
}

show_install_plan() {
    ui_section "Install plan"
    ui_kv "OS" "$OS"
    ui_kv "Method" "${INSTALL_METHOD:-auto}"
    if [[ "$INSTALL_METHOD" == "git" ]]; then
        ui_kv "Install directory" "$INSTALL_DIR"
    fi
    ui_kv "Node.js minimum" "v${MIN_NODE}+"
    ui_kv "Python" "optional (3.${MIN_PYTHON_MINOR}+)"
    if [[ "${OPT_NO_COPILOT:-false}" == "true" ]]; then
        ui_kv "Copilot" "skipped (--no-copilot)"
    fi
    if [[ "$DRY_RUN" == "1" ]]; then
        ui_kv "Dry run" "yes"
    fi
}

show_footer_links() {
    local docs_url="https://kody-w.github.io/openrappter"
    if [[ -n "$GUM" ]]; then
        local content
        content="$(printf '%s\n%s' "Need help?" "Docs: ${docs_url}")"
        ui_panel "$content"
    else
        echo ""
        echo -e "Docs: ${INFO}${docs_url}${NC}"
    fi
}

# ── Taglines ────────────────────────────────────────────────
TAGLINES=()
TAGLINES+=("Your terminal just evolved — type something and let the raptor handle the busywork.")
TAGLINES+=("Welcome to the command line: where agents compile and confidence segfaults.")
TAGLINES+=("I run on caffeine, JSON5, and the audacity of \"it worked on my machine.\"")
TAGLINES+=("Gateway online — please keep hands, feet, and appendages inside the shell at all times.")
TAGLINES+=("I speak fluent bash, mild sarcasm, and aggressive tab-completion energy.")
TAGLINES+=("One CLI to rule them all, and one more restart because you changed the port.")
TAGLINES+=("If it works, it's automation; if it breaks, it's a \"learning opportunity.\"")
TAGLINES+=("Your .env is showing; don't worry, I'll pretend I didn't see it.")
TAGLINES+=("I'll do the boring stuff while you dramatically stare at the logs like it's cinema.")
TAGLINES+=("Type the command with confidence — nature will provide the stack trace if needed.")
TAGLINES+=("I can grep it, git blame it, and gently roast it — pick your coping mechanism.")
TAGLINES+=("Hot reload for config, cold sweat for deploys.")
TAGLINES+=("I'm the assistant your terminal demanded, not the one your sleep schedule requested.")
TAGLINES+=("Automation with claws: minimal fuss, maximal pinch.")
TAGLINES+=("I'm basically a Swiss Army knife, but with more opinions and fewer sharp edges.")
TAGLINES+=("Your task has been queued; your dignity has been deprecated.")
TAGLINES+=("I can't fix your code taste, but I can fix your build and your backlog.")
TAGLINES+=("I'm not magic — I'm just extremely persistent with retries and coping strategies.")
TAGLINES+=("It's not \"failing,\" it's \"discovering new ways to configure the same thing wrong.\"")
TAGLINES+=("I read logs so you can keep pretending you don't have to.")
TAGLINES+=("I'll refactor your busywork like it owes me money.")
TAGLINES+=("I'm like tmux: confusing at first, then suddenly you can't live without me.")
TAGLINES+=("If you can describe it, I can probably automate it — or at least make it funnier.")
TAGLINES+=("Your config is valid, your assumptions are not.")
TAGLINES+=("Less clicking, more shipping, fewer \"where did that file go\" moments.")
TAGLINES+=("AI agents powered by your existing GitHub Copilot subscription.")
TAGLINES+=("No extra API keys. No new accounts. No additional monthly bills.")
TAGLINES+=("Your data stays local. Your agents stay loyal. 🦖")
TAGLINES+=("Dual runtime. Single file agents. Zero API keys.")
TAGLINES+=("Data sloshing: because your agents deserve context, not just commands.")
TAGLINES+=("Who needs API keys when you have GitHub Copilot?")
TAGLINES+=("Shell yeah — I'm here to automate the toil and leave you the glory.")
TAGLINES+=("The raptor has entered the chat. Your workflow will never be the same.")
TAGLINES+=("Local-first AI that actually remembers things. Revolutionary, we know.")
TAGLINES+=("pip install was so last season. curl | bash is the new hotness.")
TAGLINES+=("npm install -g openrappter — because you deserve nice things.")
TAGLINES+=("One command to install, zero commands to regret.")
TAGLINES+=("I'm not saying I'm better than your last framework, but… actually yes, I am.")
TAGLINES+=("Installing globally because commitment issues are for other packages.")
TAGLINES+=("Your PATH is about to get a lot more interesting.")
TAGLINES+=("Build tools? I'll handle those. You just sit there and look productive.")
TAGLINES+=("Gateway restart? More like gateway glow-up.")
TAGLINES+=("I auto-detect your install method. I'm basically psychic, but for shells.")
TAGLINES+=("npm or git? Why not both? (But npm is faster, just saying.)")
TAGLINES+=("The installer that installs installers. Wait, no — just the one you need.")
TAGLINES+=("Conflict resolution: not just for diplomats anymore.")
TAGLINES+=("Doctor's orders: your config needs a checkup after every upgrade.")

HOLIDAY_NEW_YEAR="New Year's Day: New year, new config — same old EADDRINUSE, but this time we resolve it like grown-ups."
HOLIDAY_LUNAR_NEW_YEAR="Lunar New Year: May your builds be lucky, your branches prosperous, and your merge conflicts chased away with fireworks."
HOLIDAY_CHRISTMAS="Christmas: Ho ho ho — Santa's little raptor-sistant is here to ship joy, roll back chaos, and stash the keys safely."
HOLIDAY_EID="Eid al-Fitr: Celebration mode: queues cleared, tasks completed, and good vibes committed to main with clean history."
HOLIDAY_DIWALI="Diwali: Let the logs sparkle and the bugs flee — today we light up the terminal and ship with pride."
HOLIDAY_EASTER="Easter: I found your missing environment variable — consider it a tiny CLI egg hunt with fewer jellybeans."
HOLIDAY_HANUKKAH="Hanukkah: Eight nights, eight retries, zero shame — may your gateway stay lit and your deployments stay peaceful."
HOLIDAY_HALLOWEEN="Halloween: Spooky season: beware haunted dependencies, cursed caches, and the ghost of node_modules past."
HOLIDAY_THANKSGIVING="Thanksgiving: Grateful for stable ports, working DNS, and an agent that reads the logs so nobody has to."
HOLIDAY_VALENTINES="Valentine's Day: Roses are typed, violets are piped — I'll automate the chores so you can spend time with humans."

append_holiday_taglines() {
    local today
    local month_day
    today="$(date -u +%Y-%m-%d 2>/dev/null || date +%Y-%m-%d)"
    month_day="$(date -u +%m-%d 2>/dev/null || date +%m-%d)"

    case "$month_day" in
        "01-01") TAGLINES+=("$HOLIDAY_NEW_YEAR") ;;
        "02-14") TAGLINES+=("$HOLIDAY_VALENTINES") ;;
        "10-31") TAGLINES+=("$HOLIDAY_HALLOWEEN") ;;
        "12-25") TAGLINES+=("$HOLIDAY_CHRISTMAS") ;;
    esac

    case "$today" in
        "2025-01-29"|"2026-02-17"|"2027-02-06") TAGLINES+=("$HOLIDAY_LUNAR_NEW_YEAR") ;;
        "2025-03-30"|"2025-03-31"|"2026-03-20"|"2027-03-10") TAGLINES+=("$HOLIDAY_EID") ;;
        "2025-10-20"|"2026-11-08"|"2027-10-28") TAGLINES+=("$HOLIDAY_DIWALI") ;;
        "2025-04-20"|"2026-04-05"|"2027-03-28") TAGLINES+=("$HOLIDAY_EASTER") ;;
        "2025-11-27"|"2026-11-26"|"2027-11-25") TAGLINES+=("$HOLIDAY_THANKSGIVING") ;;
        "2025-12-15"|"2025-12-16"|"2025-12-17"|"2025-12-18"|"2025-12-19"|"2025-12-20"|"2025-12-21"|"2025-12-22"|"2026-12-05"|"2026-12-06"|"2026-12-07"|"2026-12-08"|"2026-12-09"|"2026-12-10"|"2026-12-11"|"2026-12-12"|"2027-12-25"|"2027-12-26"|"2027-12-27"|"2027-12-28"|"2027-12-29"|"2027-12-30"|"2027-12-31"|"2028-01-01") TAGLINES+=("$HOLIDAY_HANUKKAH") ;;
    esac
}

pick_tagline() {
    append_holiday_taglines
    local count=${#TAGLINES[@]}
    if [[ "$count" -eq 0 ]]; then
        echo "$DEFAULT_TAGLINE"
        return
    fi
    if [[ -n "${OPENRAPPTER_TAGLINE_INDEX:-}" ]]; then
        if [[ "${OPENRAPPTER_TAGLINE_INDEX}" =~ ^[0-9]+$ ]]; then
            local idx=$((OPENRAPPTER_TAGLINE_INDEX % count))
            echo "${TAGLINES[$idx]}"
            return
        fi
    fi
    local idx=$((RANDOM % count))
    echo "${TAGLINES[$idx]}"
}

TAGLINE=$(pick_tagline)

# ── Configuration ───────────────────────────────────────────
DRY_RUN=${OPENRAPPTER_DRY_RUN:-0}
VERBOSE="${OPENRAPPTER_VERBOSE:-0}"
OPENRAPPTER_USE_GUM="${OPENRAPPTER_USE_GUM:-auto}"
HELP=0

REPO_URL="https://github.com/kody-w/openrappter.git"
INSTALL_DIR="${OPENRAPPTER_HOME:-$HOME/.openrappter}"
MIN_NODE=20
MIN_PYTHON_MINOR=10
BIN_NAME="openrappter"
NPM_PACKAGE="openrappter"

# Install method: "npm", "git", or "" (auto-detect/prompt)
INSTALL_METHOD="${OPENRAPPTER_INSTALL_METHOD:-}"
OPT_NO_PROMPT="${OPENRAPPTER_NO_PROMPT:-false}"
OPT_SET_NPM_PREFIX=false

print_usage() {
    cat <<EOF
OpenRappter installer (macOS + Linux)

Usage:
  curl -fsSL https://kody-w.github.io/openrappter/install.sh | bash
  curl -fsSL https://kody-w.github.io/openrappter/install.sh | bash -s -- [options]

Options:
  --method npm|git                   Install method (default: npm)
  --dir <path>                       Install directory for git method (default: ~/.openrappter)
  --dry-run                          Print what would happen (no changes)
  --verbose                          Print debug output
  --no-prompt                        Non-interactive mode (CI/automation)
  --set-npm-prefix                   Force npm prefix fix (Linux EACCES workaround)
  --gum                              Force gum UI if possible
  --no-gum                           Disable gum UI
  --no-copilot                       Skip Copilot setup entirely
  --no-onboard                       Skip onboard wizard
  --help, -h                         Show this help

Environment variables:
  OPENRAPPTER_HOME=...              Install directory (default: ~/.openrappter)
  OPENRAPPTER_INSTALL_METHOD=npm|git Install method override
  OPENRAPPTER_VERSION=1.4.0         Pin specific version (npm method)
  OPENRAPPTER_BETA=1                Install @beta tag (npm method)
  OPENRAPPTER_NO_PROMPT=true        Non-interactive mode
  OPENRAPPTER_DRY_RUN=1             Dry run mode
  OPENRAPPTER_VERBOSE=1             Verbose output
  OPENRAPPTER_USE_GUM=auto|1|0      Default: auto (try gum on interactive TTY)
  SHARP_IGNORE_GLOBAL_LIBVIPS=1     Skip global libvips download (set automatically)

Examples:
  curl -fsSL https://kody-w.github.io/openrappter/install.sh | bash
  curl -fsSL https://kody-w.github.io/openrappter/install.sh | bash -s -- --method npm
  curl -fsSL https://kody-w.github.io/openrappter/install.sh | bash -s -- --method git --verbose
  curl -fsSL https://kody-w.github.io/openrappter/install.sh | bash -s -- --no-prompt --no-copilot
EOF
}

parse_args() {
    while [[ $# -gt 0 ]]; do
        case "$1" in
            --method)
                INSTALL_METHOD="$2"
                shift 2
                ;;
            --no-prompt)
                OPT_NO_PROMPT=true
                shift
                ;;
            --set-npm-prefix)
                OPT_SET_NPM_PREFIX=true
                shift
                ;;
            --dry-run)
                DRY_RUN=1
                shift
                ;;
            --verbose)
                VERBOSE=1
                shift
                ;;
            --gum)
                OPENRAPPTER_USE_GUM=1
                shift
                ;;
            --no-gum)
                OPENRAPPTER_USE_GUM=0
                shift
                ;;
            --no-onboard)
                OPT_NO_ONBOARD=true
                shift
                ;;
            --no-copilot)
                OPT_NO_COPILOT=true
                shift
                ;;
            --dir)
                INSTALL_DIR="$2"
                shift 2
                ;;
            --help|-h)
                HELP=1
                shift
                ;;
            *)
                shift
                ;;
        esac
    done
}

configure_verbose() {
    if [[ "$VERBOSE" != "1" ]]; then
        return 0
    fi
    set -x
}

# ── OS & Tooling ────────────────────────────────────────────
is_root() {
    [[ "$(id -u)" -eq 0 ]]
}

maybe_sudo() {
    if is_root; then
        if [[ "${1:-}" == "-E" ]]; then
            shift
        fi
        "$@"
    else
        sudo "$@"
    fi
}

require_sudo() {
    if [[ "$OS" != "linux" ]]; then
        return 0
    fi
    if is_root; then
        return 0
    fi
    if command -v sudo &> /dev/null; then
        if ! sudo -n true >/dev/null 2>&1; then
            ui_info "Administrator privileges required; enter your password"
            sudo -v
        fi
        return 0
    fi
    ui_error "sudo is required for system installs on Linux"
    echo "  Install sudo or re-run as root."
    exit 1
}

refresh_shell_command_cache() {
    hash -r 2>/dev/null || true
}

# ── Homebrew (macOS) ────────────────────────────────────────
install_homebrew() {
    if [[ "$OS" == "macos" ]]; then
        if ! command -v brew &> /dev/null; then
            ui_info "Homebrew not found, installing"
            run_quiet_step "Installing Homebrew" run_remote_bash "https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh"

            if [[ -f "/opt/homebrew/bin/brew" ]]; then
                eval "$(/opt/homebrew/bin/brew shellenv)"
            elif [[ -f "/usr/local/bin/brew" ]]; then
                eval "$(/usr/local/bin/brew shellenv)"
            fi
            ui_success "Homebrew installed"
        else
            ui_success "Homebrew already installed"
        fi
    fi
}

# ── Node.js ─────────────────────────────────────────────────
get_node_major() {
    if command -v node &>/dev/null; then
        node --version 2>/dev/null | sed 's/^v//' | cut -d. -f1
    else
        echo "0"
    fi
}

check_node() {
    # Try to find node on PATH first
    if command -v node &>/dev/null; then
        local node_ver
        node_ver=$(node -v | cut -d'v' -f2 | cut -d'.' -f1)
        if [[ "$node_ver" -ge "$MIN_NODE" ]]; then
            ui_success "Node.js v$(node -v | cut -d'v' -f2) found"
            return 0
        else
            ui_info "Node.js $(node -v) found but need v${MIN_NODE}+"
        fi
    fi

    # Node not found or too old — try sourcing version managers
    # (they may have installed node but not sourced into this shell)
    source_nvm_if_present
    source_fnm_if_present

    # Check common install locations not yet on PATH
    local extra_paths=(
        "$HOME/.local/bin"
        "/usr/local/bin"
        "/opt/homebrew/bin"
        "$HOME/.volta/bin"
    )
    # mise shims
    local mise_data="${MISE_DATA_DIR:-$HOME/.local/share/mise}"
    if [[ -d "$mise_data/shims" ]]; then
        extra_paths+=("$mise_data/shims")
    fi
    for p in "${extra_paths[@]}"; do
        if [[ -x "$p/node" ]] && ! command -v node &>/dev/null; then
            export PATH="$p:$PATH"
        fi
    done

    refresh_shell_command_cache

    if command -v node &>/dev/null; then
        local node_ver
        node_ver=$(node -v | cut -d'v' -f2 | cut -d'.' -f1)
        if [[ "$node_ver" -ge "$MIN_NODE" ]]; then
            ui_success "Node.js v$(node -v | cut -d'v' -f2) found (via PATH discovery)"
            return 0
        else
            ui_info "Node.js $(node -v) found but need v${MIN_NODE}+ — upgrading"
            return 1
        fi
    fi

    ui_info "Node.js not found, installing it now"
    return 1
}

install_node() {
    # ── Strategy: try multiple approaches in order of preference ──
    # 1. Existing version managers (nvm, fnm, volta, mise, asdf)
    # 2. Platform package manager (Homebrew / NodeSource)
    # 3. Fresh nvm install
    # 4. Direct Node.js tarball download (last resort, no root needed)

    # Source any existing version manager environments first
    source_nvm_if_present
    source_fnm_if_present

    # 1. Try existing version managers
    if try_version_managers; then
        return 0
    fi

    # 2. Try platform package manager
    if [[ "$OS" == "macos" ]]; then
        if command -v brew &>/dev/null; then
            ui_info "Installing Node.js via Homebrew"
            if run_quiet_step "Installing node@${MIN_NODE}" brew install "node@${MIN_NODE}"; then
                brew link "node@${MIN_NODE}" --overwrite --force 2>/dev/null || true
                refresh_shell_command_cache
                if verify_node_version; then
                    ui_success "Node.js $(node --version) installed via Homebrew"
                    return 0
                fi
            fi
            ui_info "Homebrew install didn't produce a usable Node — trying next method"
        fi
    elif [[ "$OS" == "linux" ]]; then
        local nodesource_ok=false
        if command -v apt-get &>/dev/null; then
            ui_info "Installing Node.js via NodeSource (apt)"
            require_sudo
            local tmp
            tmp="$(mktempfile)"
            if download_file "https://deb.nodesource.com/setup_${MIN_NODE}.x" "$tmp" 2>/dev/null; then
                if is_root; then
                    run_quiet_step "Configuring NodeSource repository" bash "$tmp" && \
                    run_quiet_step "Installing Node.js" apt-get install -y -qq nodejs && nodesource_ok=true
                else
                    run_quiet_step "Configuring NodeSource repository" sudo -E bash "$tmp" && \
                    run_quiet_step "Installing Node.js" sudo apt-get install -y -qq nodejs && nodesource_ok=true
                fi
            fi
        elif command -v dnf &>/dev/null; then
            ui_info "Installing Node.js via NodeSource (dnf)"
            require_sudo
            local tmp
            tmp="$(mktempfile)"
            if download_file "https://rpm.nodesource.com/setup_${MIN_NODE}.x" "$tmp" 2>/dev/null; then
                if is_root; then
                    run_quiet_step "Configuring NodeSource repository" bash "$tmp" && \
                    run_quiet_step "Installing Node.js" dnf install -y -q nodejs && nodesource_ok=true
                else
                    run_quiet_step "Configuring NodeSource repository" sudo bash "$tmp" && \
                    run_quiet_step "Installing Node.js" sudo dnf install -y -q nodejs && nodesource_ok=true
                fi
            fi
        elif command -v yum &>/dev/null; then
            ui_info "Installing Node.js via NodeSource (yum)"
            require_sudo
            local tmp
            tmp="$(mktempfile)"
            if download_file "https://rpm.nodesource.com/setup_${MIN_NODE}.x" "$tmp" 2>/dev/null; then
                if is_root; then
                    run_quiet_step "Configuring NodeSource repository" bash "$tmp" && \
                    run_quiet_step "Installing Node.js" yum install -y -q nodejs && nodesource_ok=true
                else
                    run_quiet_step "Configuring NodeSource repository" sudo bash "$tmp" && \
                    run_quiet_step "Installing Node.js" sudo yum install -y -q nodejs && nodesource_ok=true
                fi
            fi
        fi

        if [[ "$nodesource_ok" == "true" ]]; then
            refresh_shell_command_cache
            if verify_node_version; then
                ui_success "Node.js $(node --version) installed via NodeSource"
                return 0
            fi
        fi
        ui_info "NodeSource install didn't succeed — trying next method"
    fi

    # 3. Try fresh nvm install
    ui_info "Trying Node.js installation via nvm (fresh install)"
    if install_node_nvm 2>/dev/null; then
        refresh_shell_command_cache
        if verify_node_version; then
            return 0
        fi
    fi
    ui_info "nvm install didn't succeed — trying direct download"

    # 4. Last resort: direct tarball download (no root needed)
    if install_node_tarball; then
        return 0
    fi

    # All methods failed — give a helpful error
    ui_error "Could not install Node.js v${MIN_NODE}+"
    echo ""
    echo "  Detected node: $(command -v node 2>/dev/null || echo 'not found')"
    echo "  Node version:  $(node --version 2>/dev/null || echo 'unknown')"
    echo "  PATH: $PATH"
    echo ""
    echo "  Manual install options:"
    echo "    https://nodejs.org/en/download"
    echo "    nvm install ${MIN_NODE}"
    echo "    brew install node@${MIN_NODE}"
    echo "    fnm install ${MIN_NODE}"
    echo "    volta install node@${MIN_NODE}"
    exit 1
}

install_node_nvm() {
    if [[ ! -d "$HOME/.nvm" ]]; then
        run_quiet_step "Installing nvm" run_remote_bash "https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh"
    fi

    export NVM_DIR="$HOME/.nvm"
    # shellcheck disable=SC1091
    [[ -s "$NVM_DIR/nvm.sh" ]] && . "$NVM_DIR/nvm.sh"

    nvm install "$MIN_NODE" --default
    nvm use "$MIN_NODE"
    ui_success "Node.js $(node --version) installed via nvm"
}

# ── Node.js verification ────────────────────────────────────
verify_node_version() {
    refresh_shell_command_cache
    if ! command -v node &>/dev/null; then
        return 1
    fi
    local ver
    ver="$(node --version 2>/dev/null | sed 's/^v//' | cut -d. -f1)"
    if [[ "$ver" -ge "$MIN_NODE" ]] 2>/dev/null; then
        return 0
    fi
    return 1
}

# ── Version Manager Detection ───────────────────────────────
source_nvm_if_present() {
    if [[ -s "$HOME/.nvm/nvm.sh" ]]; then
        export NVM_DIR="$HOME/.nvm"
        # shellcheck disable=SC1091
        . "$NVM_DIR/nvm.sh" 2>/dev/null || true
    fi
}

source_fnm_if_present() {
    if command -v fnm &>/dev/null; then
        eval "$(fnm env 2>/dev/null)" || true
    fi
}

try_version_managers() {
    # Try nvm
    if [[ -s "$HOME/.nvm/nvm.sh" ]]; then
        ui_info "Found nvm — trying to install Node.js v${MIN_NODE}"
        source_nvm_if_present
        if nvm install "$MIN_NODE" --default 2>/dev/null && nvm use "$MIN_NODE" 2>/dev/null; then
            refresh_shell_command_cache
            if verify_node_version; then
                ui_success "Node.js $(node --version) activated via nvm"
                return 0
            fi
        fi
        ui_info "nvm install didn't produce a usable Node — trying next method"
    fi

    # Try fnm
    if command -v fnm &>/dev/null; then
        ui_info "Found fnm — trying to install Node.js v${MIN_NODE}"
        if fnm install "$MIN_NODE" 2>/dev/null && fnm use "$MIN_NODE" 2>/dev/null && fnm default "$MIN_NODE" 2>/dev/null; then
            source_fnm_if_present
            refresh_shell_command_cache
            if verify_node_version; then
                ui_success "Node.js $(node --version) activated via fnm"
                return 0
            fi
        fi
        ui_info "fnm install didn't produce a usable Node — trying next method"
    fi

    # Try volta
    if command -v volta &>/dev/null; then
        ui_info "Found volta — trying to install Node.js v${MIN_NODE}"
        if volta install "node@${MIN_NODE}" 2>/dev/null; then
            refresh_shell_command_cache
            if verify_node_version; then
                ui_success "Node.js $(node --version) activated via volta"
                return 0
            fi
        fi
        ui_info "volta install didn't produce a usable Node — trying next method"
    fi

    # Try mise (formerly rtx)
    if command -v mise &>/dev/null; then
        ui_info "Found mise — trying to install Node.js v${MIN_NODE}"
        if mise install "node@${MIN_NODE}" 2>/dev/null && mise use --global "node@${MIN_NODE}" 2>/dev/null; then
            eval "$(mise env 2>/dev/null)" || true
            refresh_shell_command_cache
            if verify_node_version; then
                ui_success "Node.js $(node --version) activated via mise"
                return 0
            fi
        fi
        ui_info "mise install didn't produce a usable Node — trying next method"
    fi

    # Try asdf
    if command -v asdf &>/dev/null; then
        ui_info "Found asdf — trying to install Node.js v${MIN_NODE}"
        if asdf plugin add nodejs 2>/dev/null; then true; fi
        if asdf install nodejs "$MIN_NODE" 2>/dev/null && asdf global nodejs "$MIN_NODE" 2>/dev/null; then
            refresh_shell_command_cache
            if verify_node_version; then
                ui_success "Node.js $(node --version) activated via asdf"
                return 0
            fi
        fi
        ui_info "asdf install didn't produce a usable Node — trying next method"
    fi

    return 1
}

# ── Direct Node.js tarball download (last-resort fallback) ──
NODE_TARBALL_VERSION="${OPENRAPPTER_NODE_VERSION:-22.14.0}"

install_node_tarball() {
    local node_ver="$NODE_TARBALL_VERSION"
    local os_name arch_name
    os_name="$(uname -s | tr '[:upper:]' '[:lower:]')"
    arch_name="$(uname -m)"

    case "$arch_name" in
        x86_64|amd64) arch_name="x64" ;;
        aarch64)      arch_name="arm64" ;;
    esac

    local tarball="node-v${node_ver}-${os_name}-${arch_name}.tar.xz"
    local url="https://nodejs.org/dist/v${node_ver}/${tarball}"
    local node_dir="$INSTALL_DIR/tools/node-v${node_ver}"

    ui_info "Downloading Node.js v${node_ver} tarball directly (fallback)..."

    local tmp_tar
    tmp_tar="$(mktempfile)"

    # Try .tar.xz first, fall back to .tar.gz
    local use_xz=true
    if ! command -v xz &>/dev/null; then
        use_xz=false
    fi
    if [[ "$use_xz" == "true" ]]; then
        if ! download_file "$url" "$tmp_tar" 2>/dev/null; then
            use_xz=false
        fi
    fi
    if [[ "$use_xz" == "false" ]]; then
        tarball="node-v${node_ver}-${os_name}-${arch_name}.tar.gz"
        url="https://nodejs.org/dist/v${node_ver}/${tarball}"
        if ! download_file "$url" "$tmp_tar"; then
            ui_error "Failed to download Node.js tarball"
            return 1
        fi
    fi

    # Verify SHA-256
    local shasums_tmp
    shasums_tmp="$(mktempfile)"
    if download_file "https://nodejs.org/dist/v${node_ver}/SHASUMS256.txt" "$shasums_tmp" 2>/dev/null; then
        local expected_sha actual_sha=""
        expected_sha="$(grep "$tarball" "$shasums_tmp" | awk '{print $1}' | head -1)"
        if [[ -n "$expected_sha" ]]; then
            if command -v sha256sum &>/dev/null; then
                actual_sha="$(sha256sum "$tmp_tar" | awk '{print $1}')"
            elif command -v shasum &>/dev/null; then
                actual_sha="$(shasum -a 256 "$tmp_tar" | awk '{print $1}')"
            fi
            if [[ -n "$actual_sha" && "$actual_sha" != "$expected_sha" ]]; then
                ui_error "Node.js checksum mismatch (expected $expected_sha, got $actual_sha)"
                return 1
            fi
            if [[ -n "$actual_sha" ]]; then
                ui_success "Node.js checksum verified"
            fi
        fi
    else
        ui_warn "Could not download checksums — skipping verification"
    fi

    mkdir -p "$node_dir"
    if [[ "$use_xz" == "true" ]]; then
        if ! tar -xJf "$tmp_tar" -C "$node_dir" --strip-components=1 2>/dev/null; then
            ui_error "Failed to extract Node.js tarball (.tar.xz)"
            return 1
        fi
    else
        if ! tar -xzf "$tmp_tar" -C "$node_dir" --strip-components=1 2>/dev/null; then
            ui_error "Failed to extract Node.js tarball (.tar.gz)"
            return 1
        fi
    fi

    export PATH="$node_dir/bin:$PATH"
    refresh_shell_command_cache

    if verify_node_version; then
        ui_success "Node.js $(node --version) installed via direct download to $node_dir"
        return 0
    fi

    ui_error "Node.js tarball extracted but node binary not working"
    return 1
}

# ── npm prefix fix (Linux EACCES) ───────────────────────────
fix_npm_prefix_if_needed() {
    if [[ "$OS" != "linux" ]]; then
        return 0
    fi
    if is_root; then
        return 0
    fi

    local npm_prefix
    npm_prefix="$(npm config get prefix 2>/dev/null || true)"

    if [[ -n "$npm_prefix" && ! -w "$npm_prefix" ]]; then
        local new_prefix="$HOME/.npm-global"
        ui_info "npm prefix $npm_prefix is not writable — switching to $new_prefix"
        mkdir -p "$new_prefix"
        npm config set prefix "$new_prefix" 2>/dev/null || true
        ensure_path "$new_prefix/bin"
    fi
}

# ── Installation Method Detection ───────────────────────────
detect_existing_install() {
    # Check for npm global install
    local npm_bin=""
    npm_bin="$(npm list -g --depth=0 openrappter 2>/dev/null || true)"
    if [[ "$npm_bin" == *"openrappter"* ]]; then
        echo "npm"
        return 0
    fi

    # Check for git clone install
    if [[ -d "$INSTALL_DIR/.git" ]]; then
        echo "git"
        return 0
    fi

    echo "none"
}

choose_install_method() {
    # Already set via --method flag or env var
    if [[ -n "$INSTALL_METHOD" ]]; then
        case "$INSTALL_METHOD" in
            npm|git) return 0 ;;
            *)
                ui_error "Invalid install method: $INSTALL_METHOD (use 'npm' or 'git')"
                exit 1
                ;;
        esac
    fi

    local existing
    existing="$(detect_existing_install)"

    # No existing install — default to git (npm publish paused)
    if [[ "$existing" == "none" ]]; then
        INSTALL_METHOD="git"
        return 0
    fi

    # Existing install found — match it (or prompt)
    if [[ "$OPT_NO_PROMPT" == "true" ]]; then
        INSTALL_METHOD="$existing"
        ui_info "Existing $existing install detected, upgrading via $existing (--no-prompt)"
        return 0
    fi

    if [[ -n "$GUM" ]] && gum_is_tty; then
        ui_info "Existing $existing install detected"
        local choice
        choice="$(ui_choose "Install method:" "npm" "git")" || true
        case "$choice" in
            npm) INSTALL_METHOD="npm" ;;
            git) INSTALL_METHOD="git" ;;
            *) INSTALL_METHOD="$existing" ;;
        esac
    else
        # No TTY, default to matching existing
        INSTALL_METHOD="$existing"
        ui_info "Existing $existing install detected, upgrading in-place"
    fi
}

# ── Build Tools (Linux native modules) ─────────────────────
ensure_build_tools() {
    if [[ "$OS" != "linux" ]]; then
        return 0
    fi

    # Check if gcc and make are available
    if command -v gcc &>/dev/null && command -v make &>/dev/null; then
        return 0
    fi

    ui_info "Installing build tools for native modules"
    require_sudo

    if command -v apt-get &>/dev/null; then
        if is_root; then
            run_quiet_step "Installing build-essential" apt-get install -y -qq build-essential
        else
            run_quiet_step "Installing build-essential" sudo apt-get install -y -qq build-essential
        fi
    elif command -v dnf &>/dev/null; then
        if is_root; then
            # shellcheck disable=SC2046
            run_quiet_step "Installing Development Tools" dnf groupinstall -y -q "Development Tools"
        else
            # shellcheck disable=SC2046
            run_quiet_step "Installing Development Tools" sudo dnf groupinstall -y -q "Development Tools"
        fi
    elif command -v yum &>/dev/null; then
        if is_root; then
            # shellcheck disable=SC2046
            run_quiet_step "Installing Development Tools" yum groupinstall -y -q "Development Tools"
        else
            # shellcheck disable=SC2046
            run_quiet_step "Installing Development Tools" sudo yum groupinstall -y -q "Development Tools"
        fi
    elif command -v apk &>/dev/null; then
        if is_root; then
            run_quiet_step "Installing build-base" apk add --no-cache build-base
        else
            run_quiet_step "Installing build-base" sudo apk add --no-cache build-base
        fi
    else
        ui_warn "Could not detect package manager for build tools — native modules may fail"
        return 0
    fi

    ui_success "Build tools installed"
}

# ── npm Global Install ─────────────────────────────────────
install_via_npm() {
    ui_info "Installing openrappter via npm (global)"

    # Determine version spec
    local pkg_spec="$NPM_PACKAGE"
    if [[ -n "${OPENRAPPTER_VERSION:-}" ]]; then
        pkg_spec="${NPM_PACKAGE}@${OPENRAPPTER_VERSION}"
    elif [[ "${OPENRAPPTER_BETA:-0}" == "1" ]]; then
        pkg_spec="${NPM_PACKAGE}@beta"
    fi

    # Fix npm prefix if needed (Linux EACCES)
    if [[ "$OPT_SET_NPM_PREFIX" == "true" ]]; then
        fix_npm_prefix_if_needed
    else
        fix_npm_prefix_if_needed
    fi

    # Attempt install
    if retry 3 2 run_quiet_step "Installing $pkg_spec" npm install -g "$pkg_spec" --no-fund --no-audit; then
        ui_success "npm install succeeded"
    else
        # Retry with build tools if it looks like a gyp error
        ui_warn "npm install failed — checking if build tools are needed"
        ensure_build_tools
        if retry 2 3 run_quiet_step "Retrying $pkg_spec" npm install -g "$pkg_spec" --no-fund --no-audit; then
            ui_success "npm install succeeded (after build tools)"
        else
            ui_error "npm install -g $pkg_spec failed after retries"
            echo "  Try manually: npm install -g $pkg_spec"
            echo "  Or use git method: curl ... | bash -s -- --method git"
            exit 1
        fi
    fi

    refresh_shell_command_cache

    # Verify binary is on PATH
    if command -v openrappter &>/dev/null; then
        ui_success "openrappter binary found on PATH"
    else
        # Check npm global bin directory
        local npm_bin_dir
        npm_bin_dir="$(npm config get prefix 2>/dev/null)/bin"
        if [[ -x "$npm_bin_dir/openrappter" ]]; then
            ensure_path "$npm_bin_dir"
            ui_success "openrappter binary found at $npm_bin_dir/openrappter"
        else
            ui_warn "openrappter binary not found on PATH — you may need to restart your shell"
        fi
    fi
}

# ── npm Conflict Resolution ────────────────────────────────
resolve_npm_conflicts() {
    local bin_dir
    bin_dir="$(get_bin_dir)"

    # Remove stale launcher script from a previous git install
    # (npm creates its own symlink via package.json "bin")
    if [[ "$INSTALL_METHOD" == "npm" && -f "$bin_dir/$BIN_NAME" ]]; then
        # Check if it's our handwritten launcher (not an npm symlink)
        if grep -q "openrappter launcher" "$bin_dir/$BIN_NAME" 2>/dev/null; then
            local backup
            backup="${bin_dir}/${BIN_NAME}.git-backup.$(date +%s)"
            mv "$bin_dir/$BIN_NAME" "$backup"
            ui_info "Backed up old git launcher to $backup"
        fi
    fi

    # Remove dangling npm symlinks
    if [[ "$INSTALL_METHOD" == "git" ]]; then
        local npm_bin_dir
        npm_bin_dir="$(npm config get prefix 2>/dev/null)/bin" || true
        if [[ -n "$npm_bin_dir" && -L "$npm_bin_dir/openrappter" && ! -e "$npm_bin_dir/openrappter" ]]; then
            rm -f "$npm_bin_dir/openrappter"
            ui_info "Removed dangling npm symlink at $npm_bin_dir/openrappter"
        fi
    fi
}

# ── Gateway Daemon Restart ─────────────────────────────────
detect_and_restart_gateway() {
    local pid_file="$HOME/.openrappter/gateway.pid"
    if [[ ! -f "$pid_file" ]]; then
        return 0
    fi

    local pid
    pid="$(cat "$pid_file" 2>/dev/null || true)"
    if [[ -z "$pid" ]]; then
        return 0
    fi

    # Check if process is still alive
    if ! kill -0 "$pid" 2>/dev/null; then
        rm -f "$pid_file"
        return 0
    fi

    ui_info "Gateway daemon running (PID $pid)"

    if [[ "$OPT_NO_PROMPT" == "true" ]]; then
        ui_info "Restarting gateway (--no-prompt)"
        kill "$pid" 2>/dev/null || true
        sleep 1
        # The gateway will auto-start on next openrappter invocation
        rm -f "$pid_file"
        ui_success "Gateway stopped (will auto-start on next use)"
        return 0
    fi

    if [[ -n "$GUM" ]] && gum_is_tty; then
        local choice
        choice="$(ui_choose "Restart gateway daemon?" "Yes (recommended)" "No")" || true
        if [[ "$choice" == "Yes (recommended)" ]]; then
            kill "$pid" 2>/dev/null || true
            sleep 1
            rm -f "$pid_file"
            ui_success "Gateway stopped (will auto-start on next use)"
        else
            ui_info "Gateway left running (you may want to restart it manually)"
        fi
    else
        ui_info "Restart the gateway manually if needed: kill $pid"
    fi
}

# ── Doctor/Migration ────────────────────────────────────────
run_doctor_if_available() {
    local bin
    bin="$(resolve_openrappter_bin 2>/dev/null || true)"
    if [[ -z "$bin" ]]; then
        return 0
    fi

    # Best-effort doctor run (non-fatal)
    if "$bin" doctor --json >/dev/null 2>&1; then
        ui_success "Doctor check passed"
    else
        ui_info "Doctor check skipped (not available or non-fatal issue)"
    fi
}

# ── Git ─────────────────────────────────────────────────────
check_git() {
    if command -v git &> /dev/null; then
        ui_success "Git already installed"
        return 0
    fi
    ui_info "Git not found, installing it now"
    return 1
}

install_git() {
    if [[ "$OS" == "macos" ]]; then
        run_quiet_step "Installing Git" brew install git
    elif [[ "$OS" == "linux" ]]; then
        require_sudo
        if command -v apt-get &> /dev/null; then
            if is_root; then
                run_quiet_step "Updating package index" apt-get update -qq
                run_quiet_step "Installing Git" apt-get install -y -qq git
            else
                run_quiet_step "Updating package index" sudo apt-get update -qq
                run_quiet_step "Installing Git" sudo apt-get install -y -qq git
            fi
        elif command -v dnf &> /dev/null; then
            if is_root; then
                run_quiet_step "Installing Git" dnf install -y -q git
            else
                run_quiet_step "Installing Git" sudo dnf install -y -q git
            fi
        elif command -v yum &> /dev/null; then
            if is_root; then
                run_quiet_step "Installing Git" yum install -y -q git
            else
                run_quiet_step "Installing Git" sudo yum install -y -q git
            fi
        else
            ui_error "Could not detect package manager for Git"
            exit 1
        fi
    fi
    ui_success "Git installed"
}

# ── Python (optional) ──────────────────────────────────────
get_python_version() {
    local cmd=""
    if command -v python3 &>/dev/null; then
        cmd="python3"
    elif command -v python &>/dev/null; then
        cmd="python"
    fi

    if [[ -n "$cmd" ]]; then
        $cmd --version 2>&1 | sed 's/Python //' | head -1
    else
        echo "0.0.0"
    fi
}

check_python_meets_min() {
    local ver
    ver="$(get_python_version)"
    local major minor
    major="$(echo "$ver" | cut -d. -f1)"
    minor="$(echo "$ver" | cut -d. -f2)"

    if [[ "$major" -ge 3 ]] 2>/dev/null && [[ "$minor" -ge "$MIN_PYTHON_MINOR" ]] 2>/dev/null; then
        return 0
    fi
    return 1
}

get_python_cmd() {
    if command -v python3 &>/dev/null; then
        echo "python3"
    elif command -v python &>/dev/null; then
        echo "python"
    else
        echo ""
    fi
}

# ── PATH Management ────────────────────────────────────────
get_bin_dir() {
    if [[ -d "/usr/local/bin" ]] && [[ -w "/usr/local/bin" ]]; then
        echo "/usr/local/bin"
    else
        local user_bin="$HOME/.local/bin"
        mkdir -p "$user_bin"
        echo "$user_bin"
    fi
}

ensure_path() {
    local bin_dir="$1"
    if [[ ":$PATH:" != *":$bin_dir:"* ]]; then
        local shell_rc=""
        case "$(basename "${SHELL:-/bin/bash}")" in
            zsh)  shell_rc="$HOME/.zshrc" ;;
            bash)
                if [[ -f "$HOME/.bash_profile" ]]; then
                    shell_rc="$HOME/.bash_profile"
                else
                    shell_rc="$HOME/.bashrc"
                fi
                ;;
            fish) shell_rc="$HOME/.config/fish/config.fish" ;;
            *)    shell_rc="$HOME/.profile" ;;
        esac

        if [[ -n "$shell_rc" ]]; then
            local path_line="export PATH=\"$bin_dir:\$PATH\""
            if [[ "$(basename "${SHELL:-/bin/bash}")" == "fish" ]]; then
                path_line="set -gx PATH $bin_dir \$PATH"
            fi

            if ! grep -qF "$bin_dir" "$shell_rc" 2>/dev/null; then
                {
                    echo ""
                    echo "# Added by openrappter installer"
                    echo "$path_line"
                } >> "$shell_rc"
                ui_warn "Added $bin_dir to PATH in $shell_rc"
            fi
        fi

        export PATH="$bin_dir:$PATH"
    fi
}

path_has_dir() {
    local path="$1"
    local dir="${2%/}"
    if [[ -z "$dir" ]]; then
        return 1
    fi
    case ":${path}:" in
        *":${dir}:"*) return 0 ;;
        *) return 1 ;;
    esac
}

warn_shell_path_missing_dir() {
    local dir="${1%/}"
    local label="$2"
    if [[ -z "$dir" ]]; then
        return 0
    fi
    if path_has_dir "$ORIGINAL_PATH" "$dir"; then
        return 0
    fi

    echo ""
    ui_warn "PATH missing ${label}: ${dir}"
    echo "  This can make openrappter show as \"command not found\" in new terminals."
    echo "  Fix (zsh: ~/.zshrc, bash: ~/.bashrc):"
    echo "    export PATH=\"${dir}:\$PATH\""
}

# Determine which shell rc file was (or would be) modified
get_shell_rc_file() {
    case "$(basename "${SHELL:-/bin/bash}")" in
        zsh)  echo "$HOME/.zshrc" ;;
        bash)
            if [[ -f "$HOME/.bash_profile" ]]; then
                echo "$HOME/.bash_profile"
            else
                echo "$HOME/.bashrc"
            fi
            ;;
        fish) echo "$HOME/.config/fish/config.fish" ;;
        *)    echo "$HOME/.profile" ;;
    esac
}

# Returns true if openrappter will NOT be found in a new shell (needs PATH activation)
needs_path_activation() {
    local bin_dir="${1%/}"
    [[ -n "$bin_dir" ]] && ! path_has_dir "$ORIGINAL_PATH" "$bin_dir"
}

# ── Launcher Script ────────────────────────────────────────
create_launcher() {
    local bin_dir="$1"
    local launcher="$bin_dir/$BIN_NAME"

    cat > "$launcher" << 'LAUNCHER'
#!/usr/bin/env bash
# openrappter launcher — routes to the installed runtime
set -euo pipefail

OPENRAPPTER_HOME="${OPENRAPPTER_HOME:-$HOME/.openrappter}"

# ── Ensure Node.js is discoverable ──
# 1. Bundled Node.js (direct tarball install)
if [[ -d "$OPENRAPPTER_HOME/tools" ]]; then
    for node_dir in "$OPENRAPPTER_HOME"/tools/node-v*/bin; do
        if [[ -x "$node_dir/node" ]]; then
            export PATH="$node_dir:$PATH"
            break
        fi
    done
fi

# 2. Source nvm if needed
if [[ -s "$HOME/.nvm/nvm.sh" ]]; then
    export NVM_DIR="$HOME/.nvm"
    . "$NVM_DIR/nvm.sh" 2>/dev/null || true
fi

# 3. Source fnm if available
if command -v fnm &>/dev/null; then
    eval "$(fnm env 2>/dev/null)" || true
fi

# 4. Check common paths
for _p in "$HOME/.volta/bin" "$HOME/.local/bin" "/opt/homebrew/bin"; do
    if [[ -x "$_p/node" ]] && ! command -v node &>/dev/null; then
        export PATH="$_p:$PATH"
    fi
done

# TypeScript runtime (primary)
TS_DIR="$OPENRAPPTER_HOME/typescript"
if [[ -f "$TS_DIR/dist/index.js" ]]; then
    # Load env vars (GITHUB_TOKEN etc.)
    if [[ -f "$OPENRAPPTER_HOME/.env" ]]; then
        set -a
        # shellcheck disable=SC1091
        . "$OPENRAPPTER_HOME/.env" 2>/dev/null || true
        set +a
    fi
    if ! command -v node &>/dev/null; then
        echo "Error: Node.js not found. Install Node.js 20+ and try again."
        echo "  https://nodejs.org/en/download"
        exit 1
    fi
    exec node "$TS_DIR/dist/index.js" "$@"
fi

# Python runtime (fallback)
PY_DIR="$OPENRAPPTER_HOME/python"
if [[ -f "$PY_DIR/openrappter/cli.py" ]]; then
    if command -v python3 &>/dev/null; then
        exec python3 -m openrappter.cli "$@"
    elif command -v python &>/dev/null; then
        exec python -m openrappter.cli "$@"
    fi
fi

echo "Error: openrappter is not properly installed."
echo "Run: curl -fsSL https://kody-w.github.io/openrappter/install.sh | bash"
exit 1
LAUNCHER

    chmod +x "$launcher"
}

# ── Resolve Binary ──────────────────────────────────────────
resolve_openrappter_bin() {
    refresh_shell_command_cache
    local resolved=""
    resolved="$(type -P openrappter 2>/dev/null || true)"
    if [[ -n "$resolved" && -x "$resolved" ]]; then
        echo "$resolved"
        return 0
    fi

    local bin_dir
    bin_dir="$(get_bin_dir)"
    if [[ -x "${bin_dir}/openrappter" ]]; then
        echo "${bin_dir}/openrappter"
        return 0
    fi

    echo ""
    return 1
}

resolve_openrappter_version() {
    local version=""

    # Try openrappter --version first (works for both npm and git installs)
    local bin
    bin="$(resolve_openrappter_bin 2>/dev/null || true)"
    if [[ -n "$bin" ]]; then
        version="$("$bin" --version 2>/dev/null || true)"
    fi

    # Fall back to package.json (git install)
    if [[ -z "$version" ]]; then
        local ts_pkg="$INSTALL_DIR/typescript/package.json"
        if [[ -f "$ts_pkg" ]]; then
            version="$(node -e "console.log(require('${ts_pkg}').version)" 2>/dev/null || true)"
        fi
    fi

    # Fall back to npm list (npm install)
    if [[ -z "$version" ]]; then
        version="$(npm list -g openrappter --depth=0 2>/dev/null | grep openrappter | sed 's/.*@//' || true)"
    fi

    echo "$version"
}

# ── GitHub CLI (gh) ────────────────────────────────────────
install_gh_cli() {
    if command -v gh &>/dev/null; then
        ui_success "GitHub CLI (gh) already installed"
        return 0
    fi

    ui_info "Installing GitHub CLI (gh) for Copilot authentication"

    if [[ "$OS" == "macos" ]]; then
        if command -v brew &>/dev/null; then
            run_quiet_step "Installing gh" brew install gh
        else
            ui_warn "Homebrew not available — install gh manually: https://cli.github.com"
            return 1
        fi
    elif [[ "$OS" == "linux" ]]; then
        require_sudo
        if command -v apt-get &>/dev/null; then
            # Official GitHub APT repo
            local keyring="/usr/share/keyrings/githubcli-archive-keyring.gpg"
            if [[ ! -f "$keyring" ]]; then
                local tmp_key
                tmp_key="$(mktempfile)"
                download_file "https://cli.github.com/packages/githubcli-archive-keyring.gpg" "$tmp_key"
                if is_root; then
                    install -m 0644 "$tmp_key" "$keyring" 2>/dev/null || cp "$tmp_key" "$keyring"
                else
                    sudo install -m 0644 "$tmp_key" "$keyring" 2>/dev/null || sudo cp "$tmp_key" "$keyring"
                fi
            fi
            local list_file="/etc/apt/sources.list.d/github-cli.list"
            local arch
            arch="$(dpkg --print-architecture 2>/dev/null || echo amd64)"
            local entry="deb [arch=${arch} signed-by=${keyring}] https://cli.github.com/packages stable main"
            if is_root; then
                echo "$entry" > "$list_file"
                run_quiet_step "Updating package index" apt-get update -qq
                run_quiet_step "Installing gh" apt-get install -y -qq gh
            else
                echo "$entry" | sudo tee "$list_file" >/dev/null
                run_quiet_step "Updating package index" sudo apt-get update -qq
                run_quiet_step "Installing gh" sudo apt-get install -y -qq gh
            fi
        elif command -v dnf &>/dev/null; then
            if is_root; then
                run_quiet_step "Installing gh" dnf install -y -q 'dnf-command(config-manager)' && dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo && dnf install -y -q gh
            else
                run_quiet_step "Installing gh" sudo dnf install -y -q 'dnf-command(config-manager)' && sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo && sudo dnf install -y -q gh
            fi
        elif command -v yum &>/dev/null; then
            if is_root; then
                run_quiet_step "Installing gh" yum-config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo && yum install -y -q gh
            else
                run_quiet_step "Installing gh" sudo yum-config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo && sudo yum install -y -q gh
            fi
        else
            ui_warn "Could not auto-install gh — install manually: https://cli.github.com"
            return 1
        fi
    fi

    refresh_shell_command_cache
    if command -v gh &>/dev/null; then
        ui_success "GitHub CLI installed ($(gh --version | head -1))"
        return 0
    fi

    ui_warn "gh installation may need a new shell — continuing anyway"
    return 1
}

# ── GitHub Copilot setup (device code OAuth — no gh CLI required) ──────────

# Minimal JSON field extractor (no jq needed)
parse_json_field() {
    local json="$1" field="$2"
    # Handle both quoted string and numeric values; strip trailing }, ], whitespace
    echo "$json" | sed 's/,/\n/g' | grep "\"${field}\"" | sed 's/.*"'"${field}"'"\s*:\s*//' | sed 's/^"//' | sed 's/".*$//' | sed 's/[[:space:]}]*$//' | head -1
}

copilot_device_code_login() {
    # 1. Request device code
    local response
    response="$(curl -sS -X POST "https://github.com/login/device/code" \
        -H "Accept: application/json" \
        -H "Content-Type: application/x-www-form-urlencoded" \
        -d "client_id=Iv1.b507a08c87ecfe98&scope=read:user")"

    local user_code device_code verification_uri interval expires_in
    user_code="$(parse_json_field "$response" "user_code")"
    device_code="$(parse_json_field "$response" "device_code")"
    verification_uri="$(parse_json_field "$response" "verification_uri")"
    interval="$(parse_json_field "$response" "interval")"
    expires_in="$(parse_json_field "$response" "expires_in")"

    if [[ -z "$user_code" || -z "$device_code" ]]; then
        ui_error "Failed to get device code from GitHub" >&2
        return 1
    fi

    # Default interval/expiry if parsing failed
    interval="${interval:-5}"
    expires_in="${expires_in:-900}"

    # 2. Display code to user (stderr so subshell capture doesn't swallow it)
    echo "" >&2
    if [[ -n "$GUM" ]]; then
        local code_display
        code_display="$(printf 'Enter code: %s\nURL: %s' "$user_code" "$verification_uri")"
        "$GUM" style --border rounded --border-foreground "#10b981" --padding "1 2" --foreground "#00e5cc" --bold "$code_display" >&2
    else
        echo -e "${SUCCESS}${BOLD}  Enter this code:  ${user_code}${NC}" >&2
        echo -e "${INFO}  Open: ${verification_uri}${NC}" >&2
    fi
    echo "" >&2

    # 3. Try to open browser
    if [[ "$(uname -s)" == "Darwin" ]]; then
        open "$verification_uri" 2>/dev/null || true
    elif command -v xdg-open &>/dev/null; then
        xdg-open "$verification_uri" 2>/dev/null || true
    fi

    ui_info "Waiting for GitHub authorization..." >&2

    # 4. Poll for token
    local deadline=$((SECONDS + expires_in))
    local wait_secs="$interval"

    while [[ $SECONDS -lt $deadline ]]; do
        sleep "$wait_secs"

        local token_response
        token_response="$(curl -sS -X POST "https://github.com/login/oauth/access_token" \
            -H "Accept: application/json" \
            -H "Content-Type: application/x-www-form-urlencoded" \
            -d "client_id=Iv1.b507a08c87ecfe98&device_code=${device_code}&grant_type=urn:ietf:params:oauth:grant-type:device_code")"

        local access_token error_field
        access_token="$(parse_json_field "$token_response" "access_token")"
        error_field="$(parse_json_field "$token_response" "error")"

        if [[ -n "$access_token" && "$access_token" != "null" ]]; then
            echo "$access_token"
            return 0
        fi

        case "$error_field" in
            authorization_pending)
                # Still waiting — continue polling
                ;;
            slow_down)
                wait_secs=$((wait_secs + 2))
                ;;
            access_denied)
                ui_error "GitHub login was cancelled" >&2
                return 1
                ;;
            expired_token)
                ui_error "Device code expired — please try again" >&2
                return 1
                ;;
            *)
                if [[ -n "$error_field" ]]; then
                    ui_error "GitHub device flow error: $error_field" >&2
                    return 1
                fi
                ;;
        esac
    done

    ui_error "Device code expired — please try again" >&2
    return 1
}

copilot_validate_token() {
    local token="$1"
    local response http_code
    response="$(curl -sS -w "\n%{http_code}" \
        "https://api.github.com/copilot_internal/v2/token" \
        -H "Accept: application/json" \
        -H "Authorization: Bearer $token")"
    http_code="${response##*$'\n'}"
    [[ "$http_code" == "200" ]]
}

save_github_token_to_env() {
    local github_token="$1"
    local token_source="$2"
    local env_file="$INSTALL_DIR/.env"
    mkdir -p "$INSTALL_DIR"

    # Update or create .env
    if [[ -f "$env_file" ]]; then
        # Remove old token lines if present
        if grep -qE "^(GITHUB_TOKEN|COPILOT_GITHUB_TOKEN)=" "$env_file" 2>/dev/null; then
            local tmp_env
            tmp_env="$(mktempfile)"
            grep -vE "^(GITHUB_TOKEN|COPILOT_GITHUB_TOKEN)=" "$env_file" > "$tmp_env"
            mv "$tmp_env" "$env_file"
        fi
    else
        echo "# openrappter environment — managed by installer" > "$env_file"
        echo "" >> "$env_file"
    fi
    # Save as COPILOT_GITHUB_TOKEN — checked first by resolveGithubToken(),
    # won't be overridden by gh CLI's GITHUB_TOKEN in the environment
    echo "COPILOT_GITHUB_TOKEN=\"${github_token}\"" >> "$env_file"
    ui_success "GitHub token saved (from $token_source)"
}

setup_copilot_sdk() {
    # Skip if --no-copilot flag set
    if [[ "${OPT_NO_COPILOT:-false}" == "true" ]]; then
        ui_info "Copilot setup skipped (--no-copilot)"
        return 0
    fi

    ui_info "Setting up GitHub Copilot (direct API integration)"

    local github_token=""
    local token_source=""

    # 1. Check env vars
    if [[ -n "${COPILOT_GITHUB_TOKEN:-}" ]]; then
        github_token="$COPILOT_GITHUB_TOKEN"
        token_source="COPILOT_GITHUB_TOKEN env"
    elif [[ -n "${GH_TOKEN:-}" ]]; then
        github_token="$GH_TOKEN"
        token_source="GH_TOKEN env"
    elif [[ -n "${GITHUB_TOKEN:-}" ]]; then
        github_token="$GITHUB_TOKEN"
        token_source="GITHUB_TOKEN env"
    fi

    # 2. Try gh auth token (if gh available — nice-to-have, not required)
    if [[ -z "$github_token" ]] && command -v gh &>/dev/null; then
        local gh_token
        gh_token="$(gh auth token 2>/dev/null || true)"
        if [[ -n "$gh_token" ]]; then
            github_token="$gh_token"
            token_source="gh CLI"
        fi
    fi

    # 3. If still no token and interactive TTY — run device code OAuth
    if [[ -z "$github_token" ]] && gum_is_tty; then
        ui_info "No GitHub token found — starting device code login"
        local dc_token
        dc_token="$(copilot_device_code_login)" || true
        if [[ -n "$dc_token" ]]; then
            github_token="$dc_token"
            token_source="device code OAuth"
        fi
    fi

    # 4. Non-interactive with no token — print instructions
    if [[ -z "$github_token" ]]; then
        ui_info "No GitHub token found — run 'openrappter onboard' to configure"
        return 0
    fi

    # 5. Validate token against Copilot API
    if copilot_validate_token "$github_token"; then
        ui_success "Copilot token validated"
        save_github_token_to_env "$github_token" "$token_source"
        return 0
    fi

    # Token failed validation — if it came from gh CLI or env, try device code instead
    ui_warn "Token from ${token_source} does not have Copilot API access"
    if gum_is_tty; then
        ui_info "Starting Copilot device code login to get a valid token..."
        local dc_token
        dc_token="$(copilot_device_code_login)" || true
        if [[ -n "$dc_token" ]]; then
            if copilot_validate_token "$dc_token"; then
                ui_success "Copilot token validated"
                save_github_token_to_env "$dc_token" "device code OAuth"
                return 0
            fi
        fi
        ui_warn "Could not obtain a valid Copilot token — run 'openrappter onboard' to retry"
    else
        ui_warn "Non-interactive shell — run 'openrappter onboard' to authenticate for Copilot"
    fi
}

# ── Install via Git (extracted from original main) ─────────
install_via_git() {
    local is_upgrade=false
    if [[ -d "$INSTALL_DIR/.git" ]]; then
        is_upgrade=true
    fi

    # Git is required for this method
    if ! check_git; then
        install_git
    fi

    # Clone or update repo
    if [[ "$is_upgrade" == "true" ]]; then
        ui_info "Updating existing git installation..."
        cd "$INSTALL_DIR"
        if [[ -z "$(git -C "$INSTALL_DIR" status --porcelain 2>/dev/null || true)" ]]; then
            run_quiet_step "Updating repository" git -C "$INSTALL_DIR" pull --rebase || true
        else
            ui_info "Repo has local changes; skipping git pull"
        fi
        ui_success "Updated to latest"
    else
        if [[ -d "$INSTALL_DIR" ]]; then
            ui_warn "$INSTALL_DIR exists but is not a git repo — backing up"
            mv "$INSTALL_DIR" "${INSTALL_DIR}.bak.$(date +%s)"
        fi
        run_quiet_step "Cloning openrappter" git clone --depth 1 "$REPO_URL" "$INSTALL_DIR"
        ui_success "Cloned to $INSTALL_DIR"
    fi

    cd "$INSTALL_DIR"

    # Fix npm prefix if needed (Linux EACCES)
    fix_npm_prefix_if_needed

    # TypeScript runtime
    ui_info "Installing TypeScript dependencies"
    cd "$INSTALL_DIR/typescript"

    # Clean stale build artifacts (prevents old compiled files from lingering after upgrades)
    if [[ -d dist ]]; then
        rm -rf dist
        ui_info "Cleaned stale dist/ directory"
    fi

    if [[ -f package.json ]]; then
        if ! retry 3 2 run_quiet_step "Installing npm dependencies" npm install --no-fund --no-audit; then
            ui_error "npm install failed after retries"
            echo "  This is often caused by network issues. Try again or check your connection."
            echo "  You can also try: cd $INSTALL_DIR/typescript && npm install"
            exit 1
        fi
        ui_success "Dependencies installed"

        if ! run_quiet_step "Building TypeScript" npm run build; then
            ui_error "TypeScript build failed"
            echo "  Node version: $(node --version 2>/dev/null || echo 'unknown')"
            echo "  npm version:  $(npm --version 2>/dev/null || echo 'unknown')"
            echo "  Try: cd $INSTALL_DIR/typescript && npm run build"
            exit 1
        fi
        ui_success "TypeScript runtime built"
    else
        ui_error "package.json not found in typescript/ — repo may be incomplete"
    fi

    # Python runtime (optional)
    local python_cmd
    python_cmd="$(get_python_cmd)"

    if [[ -n "$python_cmd" ]] && check_python_meets_min; then
        HAS_PYTHON=true
        ui_success "Python $($python_cmd --version 2>&1 | sed 's/Python //') found"

        # Ensure pip is available (some Linux distros ship python3 without pip)
        if ! "$python_cmd" -m pip --version &>/dev/null; then
            ui_info "pip not found, attempting to install"
            if [[ "$OS" == "linux" ]]; then
                if command -v apt-get &>/dev/null; then
                    if is_root; then
                        run_quiet_step "Installing python3-pip" apt-get install -y -qq python3-pip python3-venv 2>/dev/null || true
                    else
                        run_quiet_step "Installing python3-pip" sudo apt-get install -y -qq python3-pip python3-venv 2>/dev/null || true
                    fi
                elif command -v dnf &>/dev/null; then
                    if is_root; then
                        run_quiet_step "Installing python3-pip" dnf install -y -q python3-pip 2>/dev/null || true
                    else
                        run_quiet_step "Installing python3-pip" sudo dnf install -y -q python3-pip 2>/dev/null || true
                    fi
                elif command -v yum &>/dev/null; then
                    if is_root; then
                        run_quiet_step "Installing python3-pip" yum install -y -q python3-pip 2>/dev/null || true
                    else
                        run_quiet_step "Installing python3-pip" sudo yum install -y -q python3-pip 2>/dev/null || true
                    fi
                elif command -v apk &>/dev/null; then
                    if is_root; then
                        run_quiet_step "Installing py3-pip" apk add --no-cache py3-pip 2>/dev/null || true
                    else
                        run_quiet_step "Installing py3-pip" sudo apk add --no-cache py3-pip 2>/dev/null || true
                    fi
                fi
            fi
            # Fallback: try ensurepip
            if ! "$python_cmd" -m pip --version &>/dev/null; then
                "$python_cmd" -m ensurepip --default-pip 2>/dev/null || true
            fi
        fi

        # Install Python package if pip is now available
        if "$python_cmd" -m pip --version &>/dev/null; then
            cd "$INSTALL_DIR/python"
            if [[ -f pyproject.toml ]]; then
                if run_quiet_step "Installing Python package" "$python_cmd" -m pip install -e . --quiet; then
                    ui_success "Python runtime installed"
                else
                    ui_warn "Python package install failed — TypeScript runtime still works"
                    HAS_PYTHON=false
                fi
            fi
        else
            ui_warn "pip unavailable — skipping Python runtime (TypeScript works fine alone)"
            HAS_PYTHON=false
        fi
    else
        ui_info "Python 3.${MIN_PYTHON_MINOR}+ not found — skipping (TypeScript works fine alone)"
    fi

    # Create launcher (only for git method — npm uses package.json bin)
    local bin_dir
    bin_dir="$(get_bin_dir)"
    create_launcher "$bin_dir"
    ensure_path "$bin_dir"
    ui_success "Created $bin_dir/$BIN_NAME"

    # PATH warning
    warn_shell_path_missing_dir "$bin_dir" "bin dir"
}

# ── Main ────────────────────────────────────────────────────
main() {
    if [[ "$HELP" == "1" ]]; then
        print_usage
        return 0
    fi

    bootstrap_gum_temp || true
    print_installer_banner
    print_gum_status
    detect_os_or_die

    # ── Stage 1: Preparing environment ──
    ui_stage "Preparing environment"

    install_homebrew

    if ! check_node; then
        install_node
    fi

    # Ensure build tools are available on Linux (for native modules like better-sqlite3)
    ensure_build_tools

    # ── Stage 2: Choose install method ──
    ui_stage "Choosing install method"

    choose_install_method

    show_install_plan

    if [[ "$DRY_RUN" == "1" ]]; then
        ui_success "Dry run complete (no changes made)"
        return 0
    fi

    # Check for existing installation (for upgrade messaging)
    local is_upgrade=false
    local existing_method
    existing_method="$(detect_existing_install)"
    if [[ "$existing_method" != "none" ]]; then
        is_upgrade=true
    fi

    # Resolve conflicts when switching methods
    resolve_npm_conflicts

    # Global flag for Python availability (set by install_via_git)
    HAS_PYTHON=false

    # ── Stage 3: Install openrappter ──
    ui_stage "Installing openrappter"

    if [[ "$INSTALL_METHOD" == "npm" ]]; then
        install_via_npm
    else
        install_via_git
    fi

    # ── Copilot SDK (for git method; npm method has .env in home dir) ──
    if [[ "$INSTALL_METHOD" == "git" ]]; then
        local env_file="$INSTALL_DIR/.env"
        if [[ -f "$env_file" ]]; then
            ui_info "Clearing old .env for fresh setup"
            rm -f "$env_file"
        fi
        setup_copilot_sdk
    else
        # For npm method, store .env in ~/.openrappter/
        mkdir -p "$HOME/.openrappter"
        INSTALL_DIR="$HOME/.openrappter"
        setup_copilot_sdk
    fi

    # ── Stage 4: Finalizing setup ──
    ui_stage "Finalizing setup"

    # Gateway restart on upgrades
    if [[ "$is_upgrade" == "true" ]]; then
        detect_and_restart_gateway
    fi

    # Doctor/migration check on upgrades
    if [[ "$is_upgrade" == "true" ]]; then
        run_doctor_if_available
    fi

    # Verify binary
    local OPENRAPPTER_BIN=""
    OPENRAPPTER_BIN="$(resolve_openrappter_bin || true)"

    if [[ -n "$OPENRAPPTER_BIN" ]]; then
        "$OPENRAPPTER_BIN" --status 2>/dev/null || true
    fi

    local installed_version
    installed_version=$(resolve_openrappter_version)

    echo ""
    if [[ -n "$installed_version" ]]; then
        ui_celebrate "🦖 openrappter installed successfully (v${installed_version})!"
    else
        ui_celebrate "🦖 openrappter installed successfully!"
    fi

    if [[ "$is_upgrade" == "true" ]]; then
        local update_messages=(
            "Leveled up! New agents unlocked. You're welcome."
            "Fresh code, same raptor. Miss me?"
            "Back and better. Did you even notice I was gone?"
            "Update complete. I learned some new tricks while I was out."
            "Upgraded! Now with 23% more data sloshing."
            "I've evolved. Try to keep up. 🦖"
            "New version, who dis? Oh right, still me but shinier."
            "Patched, polished, and ready to execute. Let's go."
            "The raptor has molted. Harder shell, sharper claws."
            "Update done! Check the changelog or just trust me, it's good."
            "I went away and came back smarter. You should try it sometime."
            "Update complete. The bugs feared me, so they left."
            "New version installed. Old version sends its regards."
            "Back online. The changelog is long but our friendship is longer."
            "Molting complete. Please don't look at my soft shell phase."
            "Version bump! Same chaos energy, fewer crashes (probably)."
        )
        local update_message
        update_message="${update_messages[RANDOM % ${#update_messages[@]}]}"
        echo -e "${MUTED}${update_message}${NC}"
    else
        local completion_messages=(
            "Ahh nice, I like it here. Got any snacks?"
            "Home sweet home. Don't worry, I won't rearrange the furniture."
            "I'm in. Let's cause some responsible chaos."
            "Installation complete. Your productivity is about to get weird."
            "Settled in. Time to automate your life whether you're ready or not."
            "Finally unpacked. Now point me at your problems."
            "*cracks claws* Alright, what are we building?"
            "The raptor has landed. Your terminal will never be the same."
            "All done! I promise to only judge your code a little bit."
            "Local-first, baby. Your data stays right here. 🦖"
        )
        local completion_message
        completion_message="${completion_messages[RANDOM % ${#completion_messages[@]}]}"
        echo -e "${MUTED}${completion_message}${NC}"
    fi
    echo ""

    # Determine if the user needs to activate PATH in their shell
    local needs_activation=false
    local shell_rc
    local bin_dir
    shell_rc="$(get_shell_rc_file)"
    bin_dir="$(get_bin_dir)"
    if needs_path_activation "$bin_dir"; then
        needs_activation=true
    fi

    ui_section "What's next"

    # Show prominent activation step FIRST if needed
    if [[ "$needs_activation" == "true" ]]; then
        echo ""
        if [[ -n "$GUM" ]]; then
            local activate_msg
            activate_msg="$(printf 'To start using openrappter, run:\n\n  source %s\n\nOr open a new terminal.' "$shell_rc")"
            "$GUM" style --border rounded --border-foreground "#FFB020" --foreground "#FFB020" --bold --padding "1 2" "$activate_msg"
        else
            echo ""
            echo -e "${WARN}${BOLD}  ╭──────────────────────────────────────────────╮${NC}"
            echo -e "${WARN}${BOLD}  │  To start using openrappter, run:            │${NC}"
            echo -e "${WARN}${BOLD}  │                                              │${NC}"
            echo -e "${WARN}${BOLD}  │    source ${shell_rc}${NC}"
            echo -e "${WARN}${BOLD}  │                                              │${NC}"
            echo -e "${WARN}${BOLD}  │  Or open a new terminal.                     │${NC}"
            echo -e "${WARN}${BOLD}  ╰──────────────────────────────────────────────╯${NC}"
        fi
        echo ""
    fi

    ui_kv "Setup wizard" "openrappter onboard"
    ui_kv "Check status" "openrappter --status"
    ui_kv "List agents" "openrappter --list-agents"
    ui_kv "Chat" "openrappter \"hello\""
    if [[ "$INSTALL_METHOD" == "git" ]]; then
        ui_kv "Install dir" "$INSTALL_DIR"
        ui_kv "Command" "$bin_dir/$BIN_NAME"
        ui_kv "Update" "cd $INSTALL_DIR && git pull && cd typescript && npm run build"
    else
        ui_kv "Method" "npm global"
        ui_kv "Update" "npm update -g openrappter"
    fi
    if [[ "$HAS_PYTHON" == "true" ]]; then
        ui_kv "Python runtime" "also installed"
    fi
    echo ""

    # Auto-run onboard wizard (skip with --no-onboard; requires TTY for interactive prompts)
    # Note: `curl | bash` redirects stdin from the pipe, so -t 0 is false even in a terminal.
    # We check /dev/tty instead and redirect stdin from it so the wizard can prompt the user.
    if [[ "${OPT_NO_ONBOARD:-false}" != "true" ]] && [[ -n "$OPENRAPPTER_BIN" ]]; then
        if [[ -e /dev/tty ]]; then
            echo ""
            ui_info "Running setup wizard..."
            echo ""
            "$OPENRAPPTER_BIN" onboard </dev/tty
        else
            echo ""
            ui_info "Non-interactive shell detected — skipping setup wizard."
            ui_info "Run 'openrappter onboard' in your terminal to complete setup."
        fi
    fi

    # Repeat the activation reminder AFTER onboard (so user sees it last)
    if [[ "$needs_activation" == "true" ]]; then
        echo ""
        if [[ -n "$GUM" ]]; then
            "$GUM" style --foreground "#FFB020" --bold "⚠ Remember: source ${shell_rc}  (or open a new terminal)"
        else
            echo -e "${WARN}${BOLD}⚠ Remember: source ${shell_rc}  (or open a new terminal)${NC}"
        fi
    fi

    show_footer_links
}

# Run main unless sourced (for testing)
if [[ "${OPENRAPPTER_INSTALL_SH_NO_RUN:-0}" != "1" ]]; then
    parse_args "$@"
    configure_verbose
    main
fi