install.sh

#!/bin/bash
# install.sh - Install ctrl-exec-agent, ctrl-exec-dispatcher, or ctrl-exec-api
# Must be run as root. Role must be specified explicitly.
#
# Usage:
#   ./install.sh --agent        Install the agent (on remote hosts)
#   ./install.sh --dispatcher   Install ctrl-exec-dispatcher (on control host)
#   ./install.sh --api          Install ctrl-exec-api (on control host, after --dispatcher)
#   ./install.sh --uninstall    Remove installed files (preserves config/certs)
#   ./install.sh --run-tests    Run test suite from the source directory
#
# Supported platforms: Debian/Ubuntu (apt), Alpine Linux (apk), OpenWrt 25.x (apk), OpenWrt 23.x and older (opkg)

set -euo pipefail

# --- configuration ---

AGENT_USER="ctrl-exec-agent"
AGENT_GROUP="ctrl-exec-agent"
EXEC_GROUP="ctrl-exec"
EXEC_USER="ctrl-exec"

BIN_DIR="/usr/local/bin"
SBIN_DIR="/usr/local/sbin"
LIB_DIR="/usr/local/lib/ctrl-exec"
AGENT_CONF_DIR="/etc/ctrl-exec-agent"
EXEC_CONF_DIR="/etc/ctrl-exec-dispatcher"
# Names used before 0.13 (T-008). Only the upgrade migration and uninstall use them.
LEGACY_EXEC_CONF_DIR="/etc/ctrl-exec"
LEGACY_EXECUTOR_SERVICE="ctrl-exec-exec.service"
LEGACY_EXECUTOR_BIN="ctrl-exec-exec"
SCRIPTS_DIR="/opt/ctrl-exec-scripts"
PAIRING_DIR="/var/lib/ctrl-exec/pairing"
AGENTS_DIR="/var/lib/ctrl-exec/agents"
LOCKS_DIR="/var/lib/ctrl-exec/locks"
RUNS_DIR="/var/lib/ctrl-exec/runs"
AGENT_RUNS_DIR="/var/lib/ctrl-exec-agent/runs"
SYSTEMD_DIR="/etc/systemd/system"
# Bash completion: the lazily loaded directory if the system has one, else the
# older source-everything directory. Empty (completion skipped) if neither exists.
if [[ -d /usr/share/bash-completion/completions ]]; then
    COMPLETION_DIR="/usr/share/bash-completion/completions"
elif [[ -d /etc/bash_completion.d ]]; then
    COMPLETION_DIR="/etc/bash_completion.d"
else
    COMPLETION_DIR=""
fi
AGENT_SERVICE="ctrl-exec-agent.service"
API_SERVICE="ctrl-exec-api.service"
EXECUTOR_SERVICE="ctrl-exec-executor.service"

# Colours
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

# --- helpers ---

info()  { echo -e "${GREEN}[INFO]${NC}  $*"; }
warn()  { echo -e "${YELLOW}[WARN]${NC}  $*"; }
error() { echo -e "${RED}[ERROR]${NC} $*" >&2; }
die()   { error "$*"; exit 1; }

check_root() {
    [[ $EUID -eq 0 ]] || die "This script must be run as root (or via sudo)."
}

# Copy a file and set permissions. Replaces coreutils 'install' which is
# absent on OpenWRT.
# Create the agent scripts directory 755 root:root. An existing directory in the
# state earlier releases created (750 root:$AGENT_GROUP, which the default
# profile's run_as user cannot enter) is brought to 755 root:root; any other
# mode or owner is the operator's choice and is left alone. Exact path only.
setup_scripts_dir() {
    if [[ ! -d "$SCRIPTS_DIR" ]]; then
        mkdir -p "$SCRIPTS_DIR"
        chmod 755 "$SCRIPTS_DIR"
        chown root:root "$SCRIPTS_DIR"
        info "Script directory created: $SCRIPTS_DIR"
    elif [[ "$(stat -c '%a %U:%G' "$SCRIPTS_DIR")" == "750 root:$AGENT_GROUP" ]]; then
        chmod 755 "$SCRIPTS_DIR"
        chown root:root "$SCRIPTS_DIR"
        info "Script directory opened to 755 root:root (was 750 root:$AGENT_GROUP): $SCRIPTS_DIR"
    else
        info "Script directory already exists: $SCRIPTS_DIR"
    fi
}

safe_install() {
    local mode="$1" src="$2" dst="$3"
    cp "$src" "$dst" || return 1
    chmod "$mode" "$dst"
}

# Install bash completion for a command (etc/bash-completion/<cmd>), plus its
# short name as a link where the completion directory loads files by command
# name. Skipped quietly when the system has no bash-completion directory.
install_completion() {
    local cmd="$1" short="${2:-}"
    [[ -n "$COMPLETION_DIR" ]] || return 0
    [[ -f "$SOURCE_DIR/etc/bash-completion/$cmd" ]] || return 0
    safe_install 644 "$SOURCE_DIR/etc/bash-completion/$cmd" "$COMPLETION_DIR/$cmd" \
        || { warn "Could not install bash completion for $cmd."; return 0; }
    if [[ -n "$short" && "$COMPLETION_DIR" == */completions ]]; then
        ln -sf "$cmd" "$COMPLETION_DIR/$short"
    fi
    info "Bash completion: $COMPLETION_DIR/$cmd${short:+ (and $short)}"
}

# Install a canonical systemd unit template (etc/systemd/) with @BINDIR@ and
# @SBINDIR@ resolved to this install's prefixes. The .deb build renders the
# same templates with /usr/bin and /usr/sbin (debian/rules).
install_unit() {
    local unit="$1"
    sh "$SOURCE_DIR/etc/systemd/render-unit" "$BIN_DIR" "$SBIN_DIR" \
        "$SOURCE_DIR/etc/systemd/$unit" "$SYSTEMD_DIR/$unit" || return 1
    chmod 644 "$SYSTEMD_DIR/$unit"
}

# --- migration of pre-0.13 installs (T-008) ---

# The dispatcher's config directory was /etc/ctrl-exec; it is now
# /etc/ctrl-exec-dispatcher (T-008, T-065). Only a real old config
# (ctrl-exec.conf and ca.key) is moved, and only when the new directory is
# absent or just the seeded example (no CA; kept aside as <new>.seeded): one
# rename, a symlink left at the old name, the paths inside ctrl-exec.conf
# pointed at the new directory (previous file kept as ctrl-exec.conf.pre-0.13).
# A mount point is never moved, and both directories holding a CA are left for
# the operator; ced and ctrl-exec-api then run in place or refuse. The deb
# postinst runs the same code, Exec::DispatcherConfig::migrate_legacy_dir
# (install_lib has installed it by now).
migrate_dispatcher_conf_dir() {
    local old="$LEGACY_EXEC_CONF_DIR"
    [[ -d "$old" && ! -L "$old" ]] || return 0
    perl -I"$LIB_DIR" -MExec::DispatcherConfig \
        -e 'Exec::DispatcherConfig::installer_migrate()' "$old" "$EXEC_CONF_DIR" \
        || warn "Config directory migration did not run; ced and ctrl-exec-api decide at start."
}

# The executor was ctrl-exec-exec (binary, ctrl-exec-exec.service); it is now
# ctrl-exec-executor. Stop and disable the old unit, remove it and the old
# binary, and give the new unit the old one's state (enabled, running). Runs
# after the new binary and unit are installed; a fresh install does nothing here.
migrate_legacy_executor() {
    local old_unit="$SYSTEMD_DIR/$LEGACY_EXECUTOR_SERVICE"
    local old_bin="$SBIN_DIR/$LEGACY_EXECUTOR_BIN"
    [[ -f "$old_unit" || -f "$old_bin" ]] || return 0
    local was_active=false was_enabled=false
    if [[ "$HAS_SYSTEMD" == true ]]; then
        systemctl is-active  --quiet "$LEGACY_EXECUTOR_SERVICE" 2>/dev/null && was_active=true
        systemctl is-enabled --quiet "$LEGACY_EXECUTOR_SERVICE" 2>/dev/null && was_enabled=true
        [[ "$was_active"  == true ]] && systemctl stop    "$LEGACY_EXECUTOR_SERVICE"
        [[ "$was_enabled" == true ]] && systemctl disable "$LEGACY_EXECUTOR_SERVICE" 2>/dev/null
    fi
    rm -f "$old_unit" "$old_bin"
    info "Removed the old executor ($LEGACY_EXECUTOR_BIN, $LEGACY_EXECUTOR_SERVICE)."
    if [[ "$HAS_SYSTEMD" == true ]]; then
        systemctl daemon-reload
        if [[ "$was_enabled" == true ]]; then
            systemctl enable "$EXECUTOR_SERVICE" 2>/dev/null \
                || warn "Could not enable $EXECUTOR_SERVICE; enable it manually."
        fi
        if [[ "$was_active" == true ]]; then
            systemctl start "$EXECUTOR_SERVICE" \
                || warn "Could not start $EXECUTOR_SERVICE; start it manually."
            info "$EXECUTOR_SERVICE started in place of $LEGACY_EXECUTOR_SERVICE."
        fi
    fi
}

# Prefix for suggested commands in next-steps output. Cleared on OpenWRT
# since the installer runs as root and sudo is not available.
SUDO_CMD="sudo"

# Resolve the directory containing this script, following symlinks
script_dir() {
    local src="${BASH_SOURCE[0]}"
    while [[ -L "$src" ]]; do
        local dir
        dir="$(cd -P "$(dirname "$src")" && pwd)"
        src="$(readlink "$src")"
        [[ "$src" != /* ]] && src="$dir/$src"
    done
    cd -P "$(dirname "$src")" && pwd
}

SOURCE_DIR="$(script_dir)"

# --- platform detection ---

PKG_MGR=""
PKG_INSTALL_CMD=""

detect_platform() {
    if [[ -f /etc/openwrt_release ]]; then
        # shellcheck source=/dev/null
        source /etc/openwrt_release
        local owrt_ver="${DISTRIB_RELEASE:-0}"
        local owrt_major="${owrt_ver%%.*}"
        if command -v apk &>/dev/null && [[ "$owrt_major" -ge 24 ]] 2>/dev/null; then
            PKG_MGR="openwrt"
            PKG_INSTALL_CMD="apk add"
            info "Platform: OpenWrt ${owrt_ver} (apk)"
            warn "OpenWrt: ensure bash is installed before running this installer (apk add bash)."
        else
            PKG_MGR="openwrt-opkg"
            PKG_INSTALL_CMD="opkg install"
            info "Platform: OpenWrt ${owrt_ver} (opkg)"
            warn "OpenWrt/opkg: ensure bash is installed before running this installer (opkg install bash)."
        fi
        SUDO_CMD=""
        mkdir -p "$BIN_DIR" "$LIB_DIR"
    elif command -v apk &>/dev/null; then
        PKG_MGR="apk"
        PKG_INSTALL_CMD="apk add"
        info "Platform: Alpine Linux (apk)"
    elif command -v apt &>/dev/null; then
        PKG_MGR="apt"
        PKG_INSTALL_CMD="apt install"
        info "Platform: Debian/Ubuntu (apt)"
    else
        die "Unsupported platform. Supported: Debian/Ubuntu (apt), Alpine Linux (apk), OpenWrt 25.x (apk), OpenWrt 23.x and older (opkg).
     For RPM-based systems, install dependencies manually and copy files directly.
     See DEVELOPER.md for file locations."
    fi
}

# --- user/group creation (platform-aware) ---

create_system_group() {
    local group="$1"

    local group_exists=false
    if command -v getent &>/dev/null; then
        getent group "$group" &>/dev/null && group_exists=true
    else
        grep -q "^${group}:" /etc/group 2>/dev/null && group_exists=true
    fi

    if [[ "$group_exists" == true ]]; then
        info "Group '$group' already exists."
        return
    fi

    info "Creating system group '$group'..."
    if [[ "$PKG_MGR" == "openwrt" || "$PKG_MGR" == "openwrt-opkg" ]]; then
        echo "${group}:x:9443:" >> /etc/group
    elif [[ "$PKG_MGR" == "apk" ]]; then
        addgroup -S "$group"
    else
        groupadd --system "$group"
    fi
}

create_system_user() {
    local user="$1"
    local group="$2"
    local comment="$3"

    if id "$user" &>/dev/null; then
        info "User '$user' already exists."
        return
    fi

    info "Creating system user '$user'..."
    if [[ "$PKG_MGR" == "openwrt" || "$PKG_MGR" == "openwrt-opkg" ]]; then
        echo "${user}:x:9443:9443:${comment}:/var/run/${user}:/bin/false" >> /etc/passwd
    elif [[ "$PKG_MGR" == "apk" ]]; then
        adduser -S -H -s /sbin/nologin -G "$group" -g "$comment" "$user"
    else
        useradd --system --no-create-home \
            --shell /usr/sbin/nologin \
            --gid "$group" \
            --comment "$comment" \
            "$user"
    fi
}

# --- init system detection ---

HAS_SYSTEMD=false
HAS_PROCD=false

detect_init() {
    if command -v systemctl &>/dev/null; then
        HAS_SYSTEMD=true
    elif [[ -f /sbin/procd ]]; then
        HAS_PROCD=true
    else
        warn "No supported init system found (systemd or procd) - service files will not be installed."
        warn "Start services manually once configured:"
        warn "  ctrl-exec-agent serve"
        warn "  ctrl-exec-api"
    fi
}

install_service_unit() {
    local unit="$1"
    if [[ "$HAS_SYSTEMD" == true ]]; then
        info "Installing systemd unit $unit..."
        install_unit "$unit"
        systemctl daemon-reload
    elif [[ "$HAS_PROCD" == true ]]; then
        local init_script="/etc/init.d/ctrl-exec-agent"
        info "Installing procd init script $init_script..."
        safe_install 755 "$SOURCE_DIR/etc/ctrl-exec-agent.init" "$init_script"
        "$init_script" enable
    fi
}

# --- dependency check ---

# Perl module => package name maps, per platform per role.
# Core modules (always present in perl/perl-base) are listed for completeness
# so missing package suggestions are accurate if something is genuinely absent.

check_perl_modules() {
    local role="$1"

    # Debian module => package
    declare -A DEB_AGENT_DEPS=(
        ["IO::Socket::SSL"]="libio-socket-ssl-perl"
        ["JSON"]="libjson-perl"
        ["File::Temp"]="perl"
        ["Sys::Syslog"]="perl"
        ["Getopt::Long"]="perl"
        ["Sys::Hostname"]="perl"
        ["POSIX"]="perl"
    )
    declare -A DEB_EXEC_DEPS=(
        ["LWP::UserAgent"]="libwww-perl"
        ["IO::Socket::SSL"]="libio-socket-ssl-perl"
        ["JSON"]="libjson-perl"
        ["File::Temp"]="perl"
        ["Sys::Syslog"]="perl"
        ["Getopt::Long"]="perl"
        ["Sys::Hostname"]="perl"
        ["Time::HiRes"]="perl"
        ["Time::Piece"]="perl"
        ["IO::Select"]="perl"
        ["POSIX"]="perl"
        ["Fcntl"]="perl"
        ["File::Path"]="perl"
        ["File::Basename"]="perl"
        ["IPC::Open2"]="perl"
    )

    # Alpine module => package
    declare -A APK_AGENT_DEPS=(
        ["IO::Socket::SSL"]="perl-io-socket-ssl"
        ["JSON"]="perl-json"
        ["File::Temp"]="perl"
        ["Sys::Syslog"]="perl"
        ["Getopt::Long"]="perl"
        ["Sys::Hostname"]="perl"
        ["POSIX"]="perl"
    )
    declare -A APK_EXEC_DEPS=(
        ["LWP::UserAgent"]="perl-libwww"
        ["IO::Socket::SSL"]="perl-io-socket-ssl"
        ["JSON"]="perl-json"
        ["File::Temp"]="perl"
        ["Sys::Syslog"]="perl"
        ["Getopt::Long"]="perl"
        ["Sys::Hostname"]="perl"
        ["Time::HiRes"]="perl"
        ["Time::Piece"]="perl"
        ["IO::Select"]="perl"
        ["POSIX"]="perl"
        ["Fcntl"]="perl"
        ["File::Path"]="perl"
        ["File::Basename"]="perl"
        ["IPC::Open2"]="perl"
    )

    # OpenWrt module => package (perlbase-* granular packaging; JSON::PP replaces JSON)
    declare -A OPENWRT_AGENT_DEPS=(
        ["IO::Socket::SSL"]="perl-io-socket-ssl"
        ["JSON::PP"]="perlbase-json-pp"
        ["File::Temp"]="perlbase-file"
        ["File::Basename"]="perlbase-file"
        ["File::Path"]="perlbase-file"
        ["Sys::Syslog"]="perlbase-sys"
        ["Sys::Hostname"]="perlbase-sys"
        ["Getopt::Long"]="perlbase-getopt"
        ["POSIX"]="perlbase-posix"
        ["Time::HiRes"]="perlbase-time"
        ["Time::Piece"]="perlbase-time"
        ["Carp"]="perlbase-essential"
        ["FindBin"]="perlbase-findbin"
    )
    declare -A OPENWRT_EXEC_DEPS=(
        ["LWP::UserAgent"]="perl-www"
        ["IO::Socket::SSL"]="perl-io-socket-ssl"
        ["JSON::PP"]="perlbase-json-pp"
        ["File::Temp"]="perlbase-file"
        ["File::Basename"]="perlbase-file"
        ["File::Path"]="perlbase-file"
        ["Sys::Syslog"]="perlbase-sys"
        ["Sys::Hostname"]="perlbase-sys"
        ["Getopt::Long"]="perlbase-getopt"
        ["POSIX"]="perlbase-posix"
        ["Time::HiRes"]="perlbase-time"
        ["Time::Piece"]="perlbase-time"
        ["IO::Select"]="perlbase-io"
        ["Fcntl"]="perlbase-fcntl"
        ["IPC::Open2"]="perlbase-ipc"
        ["Carp"]="perlbase-essential"
        ["FindBin"]="perlbase-findbin"
    )

    # OpenWrt/opkg module => package (23.x and older; IO::Socket::SSL from community feed)
    # Note: perl-io-socket-ssl is not in the official opkg feed for older releases.
    # It must be installed from the community packages feed before running this installer.
    # See: https://openwrt.org/packages/pkgdata/perl-io-socket-ssl
    declare -A OPKG_AGENT_DEPS=(
        ["IO::Socket::SSL"]="perl-io-socket-ssl"
        ["JSON::PP"]="perl-json"
        ["File::Temp"]="perlbase-file"
        ["File::Basename"]="perlbase-file"
        ["File::Path"]="perlbase-file"
        ["Sys::Syslog"]="perlbase-sys"
        ["Sys::Hostname"]="perlbase-sys"
        ["Getopt::Long"]="perlbase-getopt"
        ["POSIX"]="perlbase-posix"
        ["Time::HiRes"]="perlbase-time"
        ["Time::Piece"]="perlbase-time"
        ["Carp"]="perlbase-essential"
        ["FindBin"]="perlbase-findbin"
    )
    declare -A OPKG_EXEC_DEPS=(
        ["LWP::UserAgent"]="perl-www"
        ["IO::Socket::SSL"]="perl-io-socket-ssl"
        ["JSON::PP"]="perl-json"
        ["File::Temp"]="perlbase-file"
        ["File::Basename"]="perlbase-file"
        ["File::Path"]="perlbase-file"
        ["Sys::Syslog"]="perlbase-sys"
        ["Sys::Hostname"]="perlbase-sys"
        ["Getopt::Long"]="perlbase-getopt"
        ["POSIX"]="perlbase-posix"
        ["Time::HiRes"]="perlbase-time"
        ["Time::Piece"]="perlbase-time"
        ["IO::Select"]="perlbase-io"
        ["Fcntl"]="perlbase-fcntl"
        ["IPC::Open2"]="perlbase-ipc"
        ["Carp"]="perlbase-essential"
        ["FindBin"]="perlbase-findbin"
    )

    # Select the right map
    local map_name
    if [[ "$PKG_MGR" == "openwrt" ]]; then
        [[ "$role" == "agent" ]] && map_name="OPENWRT_AGENT_DEPS" || map_name="OPENWRT_EXEC_DEPS"
    elif [[ "$PKG_MGR" == "openwrt-opkg" ]]; then
        [[ "$role" == "agent" ]] && map_name="OPKG_AGENT_DEPS" || map_name="OPKG_EXEC_DEPS"
    elif [[ "$PKG_MGR" == "apk" ]]; then
        [[ "$role" == "agent" ]] && map_name="APK_AGENT_DEPS" || map_name="APK_EXEC_DEPS"
    else
        [[ "$role" == "agent" ]] && map_name="DEB_AGENT_DEPS" || map_name="DEB_EXEC_DEPS"
    fi

    local -n DEP_MAP="$map_name"

    local missing_mods=()
    declare -A missing_pkgs

    for mod in "${!DEP_MAP[@]}"; do
        if ! perl -e "use $mod" 2>/dev/null; then
            missing_mods+=("$mod")
            missing_pkgs["${DEP_MAP[$mod]}"]=1
        fi
    done

    if [[ ${#missing_mods[@]} -eq 0 ]]; then
        info "All Perl module dependencies satisfied."
        return 0
    fi

    echo ""
    error "Missing Perl modules:"
    for mod in $(printf '%s\n' "${missing_mods[@]}" | sort); do
        printf "    %-30s  (%s)\n" "$mod" "${DEP_MAP[$mod]}"
    done
    echo ""
    error "Install the missing packages and re-run this installer:"
    echo ""
    echo "    $SUDO_CMD $PKG_INSTALL_CMD ${!missing_pkgs[*]}"
    echo ""
    exit 1
}

check_openssl() {
    if ! command -v openssl &>/dev/null; then
        local openssl_pkg="openssl"
        [[ "$PKG_MGR" == openwrt* ]] && openssl_pkg="openssl-util"
        echo ""
        error "openssl not found. Install with:"
        echo ""
        echo "    $SUDO_CMD $PKG_INSTALL_CMD $openssl_pkg"
        echo ""
        exit 1
    fi
    info "openssl: $(openssl version)"
}

# --- shared step ---

install_lib() {
    info "Installing Perl library to $LIB_DIR..."
    mkdir -p "$LIB_DIR"
    cp -r "$SOURCE_DIR/lib/." "$LIB_DIR/"
    find "$LIB_DIR" -name '*.pm' -exec chmod 644 {} \;
    find "$LIB_DIR" -type d   -exec chmod 755 {} \;

    # Install VERSION file so API.pm can report the release version at runtime.
    if [[ -f "$SOURCE_DIR/VERSION" ]]; then
        cp "$SOURCE_DIR/VERSION" "$LIB_DIR/VERSION"
        chmod 644 "$LIB_DIR/VERSION"
    fi

    # OpenWRT ships JSON::PP but not JSON. Install a thin shim so all
    # modules can use 'use JSON' unchanged on all platforms.
    if [[ "$PKG_MGR" == openwrt* ]]; then
        info "OpenWRT: installing JSON shim (delegates to JSON::PP)..."
        cat > "$LIB_DIR/JSON.pm" << 'EOF'
package JSON;
use JSON::PP qw(encode_json decode_json);
use Exporter 'import';
our @EXPORT    = qw(encode_json decode_json);
our @EXPORT_OK = qw(encode_json decode_json);
use constant true  => JSON::PP::true;
use constant false => JSON::PP::false;
1;
EOF
        chmod 644 "$LIB_DIR/JSON.pm"
    fi
}

# --- test runner ---

run_tests() {
    info "Running test suite (v${RELEASE_VERSION})..."
    cd "$SOURCE_DIR"

    if command -v prove &>/dev/null; then
        prove -Ilib t/
        local prove_exit
        prove_exit=$?
        echo ""
        echo "Test Summary Report for v${RELEASE_VERSION}"
        [[ $prove_exit -eq 0 ]] && info "All tests passed (v${RELEASE_VERSION})." || die "Test suite failed."
    else
        # prove is in perl-utils on Alpine; fall back to running files directly
        local failed=0
        for t in t/*.t; do
            perl -Ilib "$t" || failed=1
        done
        [[ $failed -eq 0 ]] && info "All tests passed (v${RELEASE_VERSION})." || die "Test suite failed."
    fi
}

# --- OpenWRT firewall ---

# On OpenWRT, inbound TCP 7443 must be opened via UCI so the rule survives
# fw4 restarts and reboots. A uci-defaults script is written and optionally
# run immediately. The script self-removes after running.
install_openwrt_firewall() {
    local uci_defaults="/etc/uci-defaults/99-ctrl-exec-agent"
    cat > "$uci_defaults" << 'EOF'
#!/bin/sh
uci add firewall rule
uci set firewall.@rule[-1].name="Allow-ctrl-exec-agent"
uci set firewall.@rule[-1].src="wan"
uci set firewall.@rule[-1].dest_port="7443"
uci set firewall.@rule[-1].proto="tcp"
uci set firewall.@rule[-1].target="ACCEPT"
uci commit firewall
fw4 restart
rm -f /etc/uci-defaults/99-ctrl-exec-agent
EOF
    chmod 755 "$uci_defaults"
    info "OpenWRT: applying firewall rule for port 7443..."
    "$uci_defaults" && info "Firewall rule applied." \
        || warn "Firewall rule queued in $uci_defaults - will apply on next boot."
}

# --- executor build (tarball installs) ---

# EXECUTOR_PROBLEM is empty when an executor binary is in place after
# build_executor, otherwise a short statement of what is missing. The
# EXECUTOR_CONF_* flags record what settle_executor_conf did about agent.conf.
EXECUTOR_PROBLEM=""
EXECUTOR_CONF_DISABLED=false
EXECUTOR_CONF_KEPT=false

# Build the executor from src/ into $SBIN_DIR. An executor already installed by
# an earlier run is kept when this host cannot build one.
build_executor() {
    EXECUTOR_PROBLEM=""
    mkdir -p "$SBIN_DIR"
    if ! command -v gcc &>/dev/null; then
        if [[ -x "$SBIN_DIR/ctrl-exec-executor" ]]; then
            info "gcc not found - keeping the installed $SBIN_DIR/ctrl-exec-executor."
        else
            EXECUTOR_PROBLEM="gcc (a C compiler) and the libcap development headers"
            warn "gcc not found - cannot build ctrl-exec-executor."
        fi
        return 0
    fi
    if gcc -O2 -o "$SBIN_DIR/ctrl-exec-executor" \
           "$SOURCE_DIR/src/ctrl-exec-executor.c" -lcap; then
        chmod 755 "$SBIN_DIR/ctrl-exec-executor"
        info "Built ctrl-exec-executor -> $SBIN_DIR/ctrl-exec-executor"
        if [[ "$HAS_SYSTEMD" == true ]]; then
            install_unit "$EXECUTOR_SERVICE"
            systemctl daemon-reload
        fi
        migrate_legacy_executor
    elif [[ -x "$SBIN_DIR/ctrl-exec-executor" ]]; then
        warn "Could not compile ctrl-exec-executor; keeping the one already installed."
    else
        if echo '#include <sys/capability.h>' | gcc -E -x c - &>/dev/null; then
            EXECUTOR_PROBLEM="a working build of src/ctrl-exec-executor.c (see the compiler output above)"
        else
            EXECUTOR_PROBLEM="the libcap development headers (sys/capability.h)"
        fi
        warn "Could not compile ctrl-exec-executor."
    fi
}

# The packages that provide the build requirements, for this platform.
executor_build_command() {
    case "$PKG_MGR" in
        apt)  echo "$SUDO_CMD apt-get install gcc libcap-dev" ;;
        apk)  echo "$SUDO_CMD apk add gcc musl-dev libcap-dev" ;;
        *)    echo "(install a C compiler and the libcap development headers with this system's package manager)" ;;
    esac
}

# Decide what agent.conf says about the executor when it could not be built.
#
# A NEW agent.conf (from agent.conf.example, which enables executor_socket) gets
# the line commented out: otherwise the agent would start, point every run at a
# socket nobody listens on, and fail all of them. The consequence - per-script
# profiles are not applied - is stated at the end of the install, and the agent
# itself warns at start when scripts.conf names profiles with no executor_socket.
# An EXISTING agent.conf is the operator's and is never edited; if it enables
# executor_socket, runs fail with an error that names the executor (fail closed -
# nothing runs unprofiled) and the end of the install says so.
settle_executor_conf() {
    local conf="$1" kind="$2"
    [[ -n "$EXECUTOR_PROBLEM" ]] || return 0
    grep -q '^[[:space:]]*executor_socket[[:space:]]*=' "$conf" || return 0
    if [[ "$kind" == new ]]; then
        sed -i -e 's|^\([[:space:]]*\)executor_socket\([[:space:]]*=\)|# executor_socket DISABLED by install.sh: the executor could not be built here.\n# Profiles are NOT applied until it is built; then uncomment the next line.\n\1# executor_socket\2|' "$conf"
        EXECUTOR_CONF_DISABLED=true
    else
        EXECUTOR_CONF_KEPT=true
    fi
}

# Printed at the end of an agent install. Silent when the executor is in place.
print_executor_notice() {
    [[ -n "$EXECUTOR_PROBLEM" ]] || return 0
    echo ""
    echo "================================================================"
    echo " WARNING: ctrl-exec-executor was NOT built"
    echo "================================================================"
    echo ""
    echo "  Missing: $EXECUTOR_PROBLEM."
    echo "  The executor applies per-script security profiles (run_as,"
    echo "  capabilities, read-only control directories)."
    echo ""
    if [[ "$EXECUTOR_CONF_DISABLED" == true ]]; then
        echo "  $AGENT_CONF_DIR/agent.conf has executor_socket commented out, so"
        echo "  the agent will run scripts directly as the unprivileged agent user."
        echo "  Per-script profiles are NOT applied until the executor is built."
    elif [[ "$EXECUTOR_CONF_KEPT" == true ]]; then
        echo "  Your existing $AGENT_CONF_DIR/agent.conf still sets executor_socket"
        echo "  and was not changed. Until the executor is built, every run fails"
        echo "  with an error naming the executor (nothing runs unprofiled)."
        echo "  Or comment out executor_socket to run without profiles."
    fi
    echo ""
    echo "  To enable it, install the build requirements and re-run:"
    echo "       $(executor_build_command)"
    echo "       $SUDO_CMD ./install.sh --agent"
    echo "  then enable the executor (and uncomment executor_socket in agent.conf"
    echo "  if install.sh disabled it):"
    echo "       $SUDO_CMD systemctl enable --now $EXECUTOR_SERVICE"
    echo ""
    echo "================================================================"
}

# --- agent installation ---

install_agent() {
    info "Installing ctrl-exec-agent..."

    create_system_group "$AGENT_GROUP"
    create_system_user "$AGENT_USER" "$AGENT_GROUP" "ctrl-exec agent service user"

    safe_install 755 "$SOURCE_DIR/bin/ctrl-exec-agent" "$BIN_DIR/ctrl-exec-agent"
    sed -i "s|use lib \"\$Bin/../lib\";|use lib \"$LIB_DIR\";|" \
        "$BIN_DIR/ctrl-exec-agent"
    sed -i "s|our \$VERSION = .*;|our \$VERSION = '$RELEASE_VERSION';|" \
        "$BIN_DIR/ctrl-exec-agent"

    # Privileged executor (C). The agent uses it when 'executor_socket' is set in
    # agent.conf (privilege separation). Compiled here from src/; needs gcc and
    # the libcap headers. If it cannot be built, a NEW agent.conf is written with
    # executor_socket commented out (see settle_executor_conf) and the end of the
    # install says so.
    build_executor

    # Config directory - readable by agent group, not world
    mkdir -p "$AGENT_CONF_DIR"
    chmod 750 "$AGENT_CONF_DIR"
    chown root:"$AGENT_GROUP" "$AGENT_CONF_DIR"

    if [[ ! -f "$AGENT_CONF_DIR/agent.conf" ]]; then
        safe_install 640 "$SOURCE_DIR/etc/agent.conf.example" "$AGENT_CONF_DIR/agent.conf"
        chown root:"$AGENT_GROUP" "$AGENT_CONF_DIR/agent.conf"
        warn "Agent config written to $AGENT_CONF_DIR/agent.conf - review before use."
        settle_executor_conf "$AGENT_CONF_DIR/agent.conf" new
    else
        info "Agent config already exists, not overwriting."
        settle_executor_conf "$AGENT_CONF_DIR/agent.conf" existing
    fi

    if [[ ! -f "$AGENT_CONF_DIR/scripts.conf" ]]; then
        safe_install 640 "$SOURCE_DIR/etc/scripts.conf.example" "$AGENT_CONF_DIR/scripts.conf"
        chown root:"$AGENT_GROUP" "$AGENT_CONF_DIR/scripts.conf"
        warn "Empty allowlist written to $AGENT_CONF_DIR/scripts.conf - add scripts before starting."
    else
        info "Script allowlist already exists, not overwriting."
    fi

    # Optional argument-constraint hook: shipped as a reference copy only. It is
    # inactive until the operator sets auth_hook in agent.conf (off by default).
    safe_install 755 "$SOURCE_DIR/etc/auth-hook-args.example" "$AGENT_CONF_DIR/auth-hook-args.example"

    # Scripts directory - root owns, world can traverse and read. Scripts run
    # as their profile's run_as user (the shipped default profile: nobody), which
    # must be able to reach them. Root-owned and not group/other-writable is
    # what the agent and executor enforce, not secrecy.
    setup_scripts_dir

    # Agent state directory - holds the trusted-dispatcher map and the async
    # result store. The agent (running as $AGENT_USER) must rewrite the map in
    # place during cert rotation, so the directory is owned by the agent user.
    local agent_state_dir="/var/lib/ctrl-exec-agent"
    mkdir -p "$agent_state_dir"
    chmod 750 "$agent_state_dir"
    chown "$AGENT_USER":"$AGENT_GROUP" "$agent_state_dir"

    # Upgrade migration (0.9.0): an agent paired before the trusted-dispatcher
    # map existed stored a single dispatcher serial in
    # $AGENT_CONF_DIR/ctrl-exec-serial. Seed the new map from it so the agent
    # keeps trusting its dispatcher without re-pairing. The dispatcher identity
    # is unknown here, so a placeholder is used; the real identity is restored on
    # the next cert-rotation broadcast or by re-pairing.
    local old_serial_file="$AGENT_CONF_DIR/ctrl-exec-serial"
    local new_map_file="$agent_state_dir/ctrl-exec-dispatchers"
    if [[ -f "$old_serial_file" && ! -f "$new_map_file" ]]; then
        local migrated_serial
        migrated_serial=$(tr -dc '0-9a-fA-F' < "$old_serial_file" | tr 'A-F' 'a-f')
        if [[ -n "$migrated_serial" ]]; then
            printf '# migrated from ctrl-exec-serial on upgrade to 0.9.0\n%s dispatcher\n' \
                "$migrated_serial" > "$new_map_file"
            chmod 644 "$new_map_file"
            chown "$AGENT_USER":"$AGENT_GROUP" "$new_map_file"
            info "Migrated legacy dispatcher serial into the trusted-dispatcher map"
        fi
    fi

    # Async result store - the agent writes detached-job results here, keyed by
    # reqid, plus a .locks subdir for agent-side concurrency. The agent runs as
    # $AGENT_USER and must write it, so it is owned by the agent user (0750).
    # Under systemd the unit's StateDirectory also creates/owns it; this covers
    # non-systemd hosts (openrc/openwrt) and first start before the unit runs.
    if [[ ! -d "$AGENT_RUNS_DIR" ]]; then
        mkdir -p "$AGENT_RUNS_DIR"
        chmod 750 "$AGENT_RUNS_DIR"
        chown "$AGENT_USER":"$AGENT_GROUP" "$AGENT_RUNS_DIR"
        info "Async result store created: $AGENT_RUNS_DIR"
    else
        info "Async result store already exists: $AGENT_RUNS_DIR"
    fi

    # Install demonstrator script - disabled in scripts.conf by default,
    # uncomment the entry to enable it for evaluating ctrl-exec capabilities
    safe_install 755 "$SOURCE_DIR/etc/ctrl-exec-demonstrator.sh" "$SCRIPTS_DIR/ctrl-exec-demonstrator.sh"
    chown root:root "$SCRIPTS_DIR/ctrl-exec-demonstrator.sh"
    info "Demonstrator script installed at $SCRIPTS_DIR/ctrl-exec-demonstrator.sh"


    install_service_unit "$AGENT_SERVICE"

    # Cert-renewal adoption timer: when the dispatcher delivers a renewed cert the
    # agent stages it; this timer restarts the agent (only when a cert is staged)
    # so the unit's ExecStartPre promotes it. Enabled now so renewal is hands-free.
    if [[ "$HAS_SYSTEMD" == true ]]; then
        install_unit ctrl-exec-agent-renew.service
        install_unit ctrl-exec-agent-renew.timer
        systemctl daemon-reload
        systemctl enable --now ctrl-exec-agent-renew.timer 2>/dev/null \
            || warn "Could not enable ctrl-exec-agent-renew.timer; enable it manually."
    fi

    if [[ "$PKG_MGR" == openwrt* ]]; then
        install_openwrt_firewall
    fi

    info "ctrl-exec-agent installed at $BIN_DIR/ctrl-exec-agent"
    # Shortcut symlink
    ln -sf "$BIN_DIR/ctrl-exec-agent" "$BIN_DIR/cea"
    info "Shortcut: cea -> ctrl-exec-agent"
    install_completion ctrl-exec-agent cea
}

# --- ctrl-exec installation ---

install_ctrl_exec_dispatcher() {
    info "Installing the dispatcher CLI..."

    migrate_dispatcher_conf_dir

    create_system_group "$EXEC_GROUP"
    # Service user the API server runs as (a member of the ctrl-exec group). It
    # owns the dispatcher private key (still 0600) so the API can read it without
    # running as root; group members get read-only registry/run access only.
    create_system_user "$EXEC_USER" "$EXEC_GROUP" "ctrl-exec dispatcher service user"

    safe_install 755 "$SOURCE_DIR/bin/ctrl-exec-dispatcher" "$BIN_DIR/ctrl-exec-dispatcher"
    sed -i "s|use lib \"\$Bin/../lib\";|use lib \"$LIB_DIR\";|" \
        "$BIN_DIR/ctrl-exec-dispatcher"
    sed -i "s|our \$VERSION = .*;|our \$VERSION = '$RELEASE_VERSION';|" \
        "$BIN_DIR/ctrl-exec-dispatcher"

    # Config directory
    mkdir -p "$EXEC_CONF_DIR"
    chmod 750 "$EXEC_CONF_DIR"
    chown root:"$EXEC_GROUP" "$EXEC_CONF_DIR"

    # Pairing queue
    mkdir -p "$PAIRING_DIR"
    chown root:"$EXEC_GROUP" "$PAIRING_DIR"
    chmod 770 "$PAIRING_DIR"

    # Shared runtime dirs. setgid (2770) so files created by the root CLI and by
    # the unprivileged ctrl-exec API alike inherit the ctrl-exec group - each can
    # then read (and, for locks, flock) what the other wrote.

    # Agent registry - written by approve, read by list-agents and API
    mkdir -p "$AGENTS_DIR"
    chown root:"$EXEC_GROUP" "$AGENTS_DIR"
    chmod 2770 "$AGENTS_DIR"

    # Lock files - written during dispatch
    mkdir -p "$LOCKS_DIR"
    chown root:"$EXEC_GROUP" "$LOCKS_DIR"
    chmod 2770 "$LOCKS_DIR"

    mkdir -p "$RUNS_DIR"
    chown root:"$EXEC_GROUP" "$RUNS_DIR"
    chmod 2770 "$RUNS_DIR"

    # Migrate files created before the API was de-rooted (root-group) to the
    # ctrl-exec group so the now-unprivileged API can read run records and flock
    # locks the root CLI created.
    chgrp -R "$EXEC_GROUP" "$AGENTS_DIR" "$LOCKS_DIR" "$RUNS_DIR" 2>/dev/null || true
    find "$LOCKS_DIR" -type f -exec chmod g+w {} + 2>/dev/null || true

    # ctrl-exec config
    if [[ ! -f "$EXEC_CONF_DIR/ctrl-exec.conf" ]]; then
        safe_install 640 "$SOURCE_DIR/etc/ctrl-exec.conf.example" "$EXEC_CONF_DIR/ctrl-exec.conf"
        chown root:"$EXEC_GROUP" "$EXEC_CONF_DIR/ctrl-exec.conf"
        warn "ctrl-exec config written to $EXEC_CONF_DIR/ctrl-exec.conf - review before use."
    else
        info "ctrl-exec config already exists, not overwriting."
    fi

    # Auth hook - install example only if not already present. The seeded conf
    # does not name it (T-046): it authorises everything, so it stays inactive
    # until the operator sets auth_hook; with none, api_auth_default = deny.
    if [[ ! -f "$EXEC_CONF_DIR/auth-hook" ]]; then
        safe_install 755 "$SOURCE_DIR/etc/auth-hook.example" "$EXEC_CONF_DIR/auth-hook"
        info "Example auth hook installed at $EXEC_CONF_DIR/auth-hook (allows everything; NOT active)."
        info "ced (CLI) works as installed. The API denies every request until you edit the hook"
        info "and uncomment the auth_hook line in $EXEC_CONF_DIR/ctrl-exec.conf, then restart ctrl-exec-api."
    else
        info "Auth hook already exists, not overwriting."
    fi

    # Migration: hand an existing dispatcher private key to the service user (still
    # 0600) so the unprivileged API can read it. New keys are chowned at generation
    # by setup-ctrl-exec/rotate-cert; this covers a re-run over a pre-de-rooting
    # install. Resolve the configured key path, default to dispatcher.key.
    local key_path
    key_path=$(sed -n 's/^[[:space:]]*key[[:space:]]*=[[:space:]]*//p' \
               "$EXEC_CONF_DIR/ctrl-exec.conf" 2>/dev/null | head -n1)
    [[ -n "$key_path" ]] || key_path="$EXEC_CONF_DIR/dispatcher.key"
    if [[ -f "$key_path" ]]; then
        chown "$EXEC_USER":"$EXEC_GROUP" "$key_path"
        chmod 600 "$key_path"
    fi

    # Certificate maintenance timer: periodically pings agents (triggering renewal
    # of any cert past half-life) and rotates the dispatcher's own cert. Runs as
    # root for CA-key access. Enabled now so cert lifecycle is hands-free.
    if [[ "$HAS_SYSTEMD" == true ]]; then
        install_unit ctrl-exec-maintenance.service
        install_unit ctrl-exec-maintenance.timer
        systemctl daemon-reload
        systemctl enable --now ctrl-exec-maintenance.timer 2>/dev/null \
            || warn "Could not enable ctrl-exec-maintenance.timer; enable it manually."
    fi

    info "ctrl-exec-dispatcher installed at $BIN_DIR/ctrl-exec-dispatcher"

    # Shortcut symlink
    ln -sf "$BIN_DIR/ctrl-exec-dispatcher" "$BIN_DIR/ced"
    info "Shortcut: ced -> ctrl-exec-dispatcher"
    install_completion ctrl-exec-dispatcher ced
}

# --- api installation ---

install_api() {
    info "Installing ctrl-exec-api..."

    safe_install 755 "$SOURCE_DIR/bin/ctrl-exec-api" "$BIN_DIR/ctrl-exec-api"
    sed -i "s|use lib \"\$Bin/../lib\";|use lib \"$LIB_DIR\";|" \
        "$BIN_DIR/ctrl-exec-api"
    sed -i "s|our \$VERSION = .*;|our \$VERSION = '$RELEASE_VERSION';|" \
        "$BIN_DIR/ctrl-exec-api"

    install_service_unit "$API_SERVICE"

    info "ctrl-exec-api installed at $BIN_DIR/ctrl-exec-api"
    install_completion ctrl-exec-api
}

# --- uninstall ---

uninstall() {
    info "Uninstalling ctrl-exec..."

    if [[ "$HAS_SYSTEMD" == true ]]; then
        if systemctl is-active --quiet "$AGENT_SERVICE" 2>/dev/null; then
            info "Stopping $AGENT_SERVICE..."
            systemctl stop "$AGENT_SERVICE"
        fi
        if systemctl is-enabled --quiet "$AGENT_SERVICE" 2>/dev/null; then
            info "Disabling $AGENT_SERVICE..."
            systemctl disable "$AGENT_SERVICE"
        fi
        # The executor (and the pre-0.13 ctrl-exec-exec, if it is still around).
        for svc in "$EXECUTOR_SERVICE" "$LEGACY_EXECUTOR_SERVICE"; do
            if systemctl is-active --quiet "$svc" 2>/dev/null; then
                info "Stopping $svc..."
                systemctl stop "$svc"
            fi
            if systemctl is-enabled --quiet "$svc" 2>/dev/null; then
                info "Disabling $svc..."
                systemctl disable "$svc"
            fi
        done
    elif [[ "$HAS_PROCD" == true ]]; then
        local init_script="/etc/init.d/ctrl-exec-agent"
        if [[ -f "$init_script" ]]; then
            info "Stopping and disabling procd service..."
            "$init_script" stop  2>/dev/null || true
            "$init_script" disable 2>/dev/null || true
        fi
    fi

    local files=(
        "$BIN_DIR/ctrl-exec-agent"
        "$BIN_DIR/ctrl-exec-dispatcher"
        "$BIN_DIR/ctrl-exec-api"
        "$BIN_DIR/ced"
        "$BIN_DIR/cea"
        "$SBIN_DIR/ctrl-exec-executor"
        "$SBIN_DIR/$LEGACY_EXECUTOR_BIN"
    )

    if [[ -n "$COMPLETION_DIR" ]]; then
        local c
        # short-name links first: a link to a file already removed is dangling
        for c in ced cea ctrl-exec-agent ctrl-exec-dispatcher ctrl-exec-api; do
            files+=( "$COMPLETION_DIR/$c" )
        done
    fi

    if [[ "$HAS_SYSTEMD" == true ]]; then
        files+=(
            "$SYSTEMD_DIR/$AGENT_SERVICE"
            "$SYSTEMD_DIR/$API_SERVICE"
            "$SYSTEMD_DIR/$EXECUTOR_SERVICE"
            "$SYSTEMD_DIR/$LEGACY_EXECUTOR_SERVICE"
        )
    elif [[ "$HAS_PROCD" == true ]]; then
        files+=( "/etc/init.d/ctrl-exec-agent" )
    fi

    # Remove lock files (transient, not config)
    if [[ -d "$LOCKS_DIR" ]]; then
        rm -rf "$LOCKS_DIR"
        info "Removed $LOCKS_DIR"
    fi

    # Remove run result store (transient, not config)
    if [[ -d "$RUNS_DIR" ]]; then
        rm -rf "$RUNS_DIR"
        info "Removed $RUNS_DIR"
    fi

    # Remove the agent async result store (transient, not config)
    if [[ -d "$AGENT_RUNS_DIR" ]]; then
        rm -rf "$AGENT_RUNS_DIR"
        info "Removed $AGENT_RUNS_DIR"
    fi

    for f in "${files[@]}"; do
        if [[ -f "$f" ]]; then
            rm -f "$f"
            info "Removed $f"
        fi
    done

    if [[ -d "$LIB_DIR" ]]; then
        rm -rf "$LIB_DIR"
        info "Removed $LIB_DIR"
    fi

    if [[ "$HAS_SYSTEMD" == true ]]; then
        systemctl daemon-reload 2>/dev/null || true
    fi

    echo ""
    warn "The following were NOT removed (may contain keys, certs, or data):"
    warn "  $AGENT_CONF_DIR"
    warn "  $EXEC_CONF_DIR"
    warn "  $PAIRING_DIR"
    warn "  $AGENTS_DIR"
    warn "  $SCRIPTS_DIR"
    warn ""
    warn "To remove completely:"
    warn "  $SUDO_CMD rm -rf $AGENT_CONF_DIR $EXEC_CONF_DIR"
    warn "  $SUDO_CMD rm -rf /var/lib/ctrl-exec $SCRIPTS_DIR"
    if [[ "$PKG_MGR" == "apk" || "$PKG_MGR" == "openwrt" || "$PKG_MGR" == "openwrt-opkg" ]]; then
        warn "  $SUDO_CMD deluser $AGENT_USER"
        warn "  $SUDO_CMD delgroup $EXEC_GROUP"
    else
        warn "  $SUDO_CMD userdel $AGENT_USER"
        warn "  $SUDO_CMD groupdel $EXEC_GROUP"
    fi

    info "Uninstall complete."
}

# --- after an upgrade ---

# After an upgrade, print what doctor finds (T-055): report only, never --fix,
# and its exit status never fails the install. --brief lists the problems and
# counts the notes, so a host with nothing to fix gets one line.
run_doctor() {
    local prog="$1"
    info "Checking the upgraded install: $prog doctor --brief"
    "$BIN_DIR/$prog" doctor --brief || true
}

# --- next steps ---

print_next_steps_agent() {
    local svc_note=""
    if [[ "$HAS_SYSTEMD" == true ]]; then
        svc_note="  5. Enable and start:
       $SUDO_CMD systemctl enable $AGENT_SERVICE
       $SUDO_CMD systemctl start  $AGENT_SERVICE"
    elif [[ "$HAS_PROCD" == true ]]; then
        svc_note="  5. Enable and start:
       /etc/init.d/ctrl-exec-agent enable
       /etc/init.d/ctrl-exec-agent start"
    else
        svc_note="  5. Start the agent:
       ctrl-exec-agent serve"
    fi

    echo ""
    echo "================================================================"
    echo " ctrl-exec-agent installed"
    echo "================================================================"
    echo ""
    if [[ "$PKG_MGR" == openwrt* ]]; then
        echo "  Note: /usr/local/bin is not in the default PATH on OpenWrt."
        echo "  Add it to your session or profile:"
        echo "       export PATH=\$PATH:/usr/local/bin"
        echo "  Or add to /etc/profile for persistence."
        echo ""
    fi
    echo "Next steps:"
    echo ""
    echo "  1. Edit the script allowlist:"
    echo "       $SUDO_CMD \${EDITOR:-vi} $AGENT_CONF_DIR/scripts.conf"
    echo ""
    echo "  2. Place scripts in $SCRIPTS_DIR:"
    echo "       $SUDO_CMD cp your-script.sh $SCRIPTS_DIR/"
    echo "       $SUDO_CMD chmod 755 $SCRIPTS_DIR/your-script.sh"
    echo "       $SUDO_CMD chown root:root $SCRIPTS_DIR/your-script.sh"
    echo "     (755 root:root lets the default profile's run_as user, nobody, run it.)"
    echo ""
    echo "  3. Request pairing (while the dispatcher host is in pairing-mode):"
    echo "       $SUDO_CMD ctrl-exec-agent request-pairing --dispatcher <dispatcher-host>"
    echo ""
    echo "  4. Once approved, verify:"
    echo "       $SUDO_CMD ctrl-exec-agent pairing-status"
    echo "       $SUDO_CMD ctrl-exec-agent self-check"
    echo ""
    echo -e "$svc_note"
    echo ""
    echo "================================================================"
    print_executor_notice
}

print_next_steps_ctrl_exec_dispatcher() {
    echo ""
    echo "================================================================"
    echo " ctrl-exec-dispatcher installed  (shortcut: ced)"
    echo "================================================================"
    echo ""
    echo "Next steps:"
    echo ""
    echo "  1. Initialise the CA (first time only):"
    echo "       $SUDO_CMD ctrl-exec-dispatcher setup-ca"
    echo ""
    echo "  2. Generate the dispatcher certificate:"
    echo "       $SUDO_CMD ctrl-exec-dispatcher setup-ctrl-exec"
    echo ""
    echo "  3. Add yourself to the ctrl-exec group for CLI access without sudo:"
    if [[ "$PKG_MGR" == openwrt* ]]; then
        echo "       # Edit /etc/group and add your username to the $EXEC_GROUP entry"
    else
        echo "       $SUDO_CMD usermod -aG $EXEC_GROUP \$USER"
        echo "       # log out and back in, then use 'ced' as shortcut"
    fi
    echo ""
    echo "  4. Accept pairing requests from agents:"
    echo "       $SUDO_CMD ctrl-exec-dispatcher pairing-mode"
    echo ""
    echo "  5. Run a script on a paired host:"
    echo "       ctrl-exec-dispatcher run <host> <script>   # or: ced run <host> <script>"
    echo "       ctrl-exec-dispatcher ping <host>           # or: ced ping <host>"
    echo ""
    echo "     Note: the agent must be running on the target host before"
    echo "     ping or run will succeed. On the agent host:"
    echo "       $SUDO_CMD systemctl start ctrl-exec-agent   # systemd"
    echo "       /etc/init.d/ctrl-exec-agent start      # procd (OpenWrt)"
    echo "       $SUDO_CMD ctrl-exec-agent serve             # manual / no init"
    echo ""
    echo "================================================================"
}

print_next_steps_api() {
    local svc_note=""
    if [[ "$HAS_SYSTEMD" == true ]]; then
        svc_note="  1. Enable and start the API service:
       $SUDO_CMD systemctl enable $API_SERVICE
       $SUDO_CMD systemctl start  $API_SERVICE"
    else
        svc_note="  1. Start the API server:
       ctrl-exec-api"
    fi

    echo ""
    echo "================================================================"
    echo " ctrl-exec-api installed"
    echo "================================================================"
    echo ""
    echo "Next steps:"
    echo ""
    echo -e "$svc_note"
    echo ""
    echo "  2. Verify it is running:"
    echo "       curl -s http://localhost:7445/health | python3 -m json.tool"
    echo ""
    echo "  3. Test ping and discovery:"
    echo "       curl -s -X POST http://localhost:7445/ping \\"
    echo "         -H 'Content-Type: application/json' \\"
    echo "         -d '{\"hosts\":[\"<agent-host>\"]}' | python3 -m json.tool"
    echo ""
    echo "       curl -s http://localhost:7445/discovery | python3 -m json.tool"
    echo ""
    echo "  Note: For same-host callers, set api_socket = /run/ctrl-exec-api/api.sock"
    echo "        in ctrl-exec.conf (a 0660 unix socket; see api_socket_group). To"
    echo "        enable TLS on the TCP port, set api_tls_cert and api_tls_key. Send"
    echo "        confidential run input only over the socket or TLS. Restart the"
    echo "        service after either change."
    echo ""
    echo "================================================================"
}

# --- main ---

# Parse arguments and drive the installation. Wrapped in a function and
# guarded below so the script can be sourced (e.g. by t/install-version.t)
# to exercise individual helpers like install_lib() without running an
# install.
main() {
    ROLE=""
    DO_UNINSTALL=false
    DO_RUN_TESTS=false

    for arg in "$@"; do
        case "$arg" in
            --agent)      ROLE="agent" ;;
            --dispatcher) ROLE="ctrl-exec-dispatcher" ;;
            --api)        ROLE="api" ;;
            --uninstall)  DO_UNINSTALL=true ;;
            --run-tests)  DO_RUN_TESTS=true ;;
            --help|-h)
                echo "Usage: $0 --agent | --dispatcher | --api | --uninstall [--run-tests]"
                echo ""
                echo "  --agent        Install the agent service (on remote hosts)"
                echo "  --dispatcher   Install ctrl-exec-dispatcher (on control host)"
                echo "  --api          Install ctrl-exec-api (on control host, after --dispatcher)"
                echo "  --uninstall    Remove installed files (config, certs, and agent registry preserved)"
                echo "  --run-tests    Run test suite from source directory after installation"
                echo ""
                echo "Supported platforms: Debian/Ubuntu (apt), Alpine Linux (apk), OpenWrt 25.x (apk), OpenWrt 23.x and older (opkg)"
                exit 0
                ;;
            *)
                die "Unknown argument: $arg. Use --help for usage."
                ;;
        esac
    done

    check_root
    detect_platform
    detect_init

    # Read release version - present in distributed tarballs, absent in dev checkouts
    if [[ -f "$SOURCE_DIR/VERSION" ]]; then
        RELEASE_VERSION=$(cat "$SOURCE_DIR/VERSION" | tr -d '[:space:]')
    else
        RELEASE_VERSION="UNINSTALLED"
    fi

    if [[ "$DO_UNINSTALL" == true ]]; then
        uninstall
        exit 0
    fi

    # Allow --run-tests without a role (runs tests from source dir only)
    if [[ "$DO_RUN_TESTS" == true && -z "$ROLE" ]]; then
        run_tests
        exit 0
    fi

    [[ -n "$ROLE" ]] || die "Role must be specified. Use --agent, --dispatcher, --api, --uninstall, or --run-tests. See --help."

    check_openssl
    check_perl_modules "$ROLE"
    install_lib

    # An existing config means this run upgrades the role (doctor runs after it).
    local upgrade=false
    case "$ROLE" in
        agent)
            if [[ -f "$AGENT_CONF_DIR/agent.conf" ]]; then
                upgrade=true
            fi
            install_agent
            if [[ "$upgrade" == true ]]; then
                run_doctor ctrl-exec-agent
            fi
            print_next_steps_agent
            ;;
        ctrl-exec-dispatcher)
            if [[ -f "$EXEC_CONF_DIR/ctrl-exec.conf" || -f "$LEGACY_EXEC_CONF_DIR/ctrl-exec.conf" ]]; then
                upgrade=true
            fi
            install_ctrl_exec_dispatcher
            if [[ "$upgrade" == true ]]; then
                run_doctor ctrl-exec-dispatcher
            fi
            print_next_steps_ctrl_exec_dispatcher
            ;;
        api)
            # API requires the dispatcher role to already be installed
            migrate_dispatcher_conf_dir
            if [[ ! -f "$EXEC_CONF_DIR/ctrl-exec.conf" ]]; then
                die "--api requires --dispatcher to be installed first."
            fi
            install_api
            print_next_steps_api
            ;;
    esac

    if [[ "$DO_RUN_TESTS" == true ]]; then
        run_tests
    fi
}

# Run main only when executed directly, not when sourced.
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
    main "$@"
fi