Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

23.1 KB
Raw Blame
# _install-common.sh — shared helpers for the .sh installers.
#
# Bash counterpart to CuaDriverInstall.psm1. Both files have to stay in
# lockstep on the kill / probe behaviour so a Mac/Linux dev fix matches
# what install.ps1 does on Windows. Function names mirror the
# PowerShell side:
#
#   stop_cua_driver_daemons          ↔  Stop-CuaDriverDaemons
#   show_cua_driver_daemon_survivors ↔  Show-CuaDriverDaemonSurvivors
#
# macOS-only, no PowerShell counterpart:
#
#   cua_driver_release_processes      — every process of the current user that
#                                       runs a com.trycua.driver bundle, wherever
#                                       the app lives and whatever its version
#   cua_driver_stop_release_processes — stop those: graceful, then TERM, then KILL
#   unregister_other_cua_driver_copies — make LaunchServices forget every other
#                                       copy of the app (never deletes files)
#
# This script is sourced (not exec'd) by the Rust install helpers:
#
#   * _install-rust.sh           (production Rust delegate)
#   * _install-local-rust.sh     (dev Rust installer)
#
# Loaders: on-disk first when run from a checked-out tree, else fetched
# from GitHub raw via `curl` (mirrors the irm | iex path that
# install.ps1 uses to import the .psm1 over the network). The inline
# loader is duplicated in each consumer because `source` doesn't have a
# bootstrap function the way PowerShell's `Import-Module` does — kept
# minimal so the duplication cost stays low.
#
# Keep this file narrow on purpose: every byte gets curl'd on every
# `curl ... | bash` install on non-macOS hosts (where install.sh
# auto-delegates to the Rust path) AND on dev installs. Things that DO
# belong here: kill / wait / probe helpers that multiple consumers
# need. Things that DON'T: anything only one script uses (leave it
# inline there).
#
# Style:
#   * No `set -e` — sourced helpers shouldn't change the caller's shell
#     options. Caller scripts are already `set -euo pipefail`.
#   * Best-effort everywhere: every external command is suffixed with
#     `|| true` (or wrapped in a subshell) so a kill failure never
#     aborts the surrounding install.
#   * Bash 3.2 compatible (macOS default). No associative arrays, no
#     `[[ =~ ]]` patterns that need bash 4+.

# Best-effort kill of any running cua-driver daemons so the next
# `cua-driver` invocation starts the FRESH binary, not whatever's still
# in memory from the pre-upgrade install. Without this the previous
# daemon keeps running (and on macOS keeps holding TCC-attributed file
# handles) until the user logs out — which surfaces as "the bug I just
# fixed is still there" because the in-memory code is pre-fix.
#
# Layered escalation, in order of decreasing politeness:
#   1. macOS: `launchctl unload <plist>` on the Rust LaunchAgent
#      (com.trycua.cua-driver-rs.plist). Unload
#      is the documented way to stop a launchd-managed daemon — it
#      also clears the KeepAlive flag so launchd doesn't immediately
#      respawn the process we're about to kill. No-op (with stderr
#      suppressed) when the plist isn't installed.
#      Linux: `systemctl --user stop cua-driver-rs.service` for the
#      install-local --autostart path. Same shape — politely stop the
#      supervisor first so it doesn't restart the process.
#   2. `pkill -x cua-driver` as the backstop for processes that weren't
#      launchd/systemd-supervised (e.g. a manual `cua-driver serve`
#      from a dev shell, or `cua-driver mcp` spawned by an editor that
#      isn't aware we're swapping the binary out from under it).
#
# Daemon-name coverage:
#   The Rust binary execs as `cua-driver`. One `pkill -x cua-driver`
#   stops it. `cua-driver-uia` is a Windows-only helper (see
#   libs/cua-driver/rust/crates/cua-driver-uia/) and never exists on
#   macOS/Linux, so no pkill for it here.
#
# Returns: always 0. Caller threads this through unconditionally; the
# behaviour is "kill what we can, never block the install".
stop_cua_driver_daemons() {
    printf '==> stopping any running cua-driver daemons before swap\n'

    # Wrap the whole thing in a subshell so any unexpected non-zero exit
    # (e.g. a `pkill` returning 1 when no process matches under a
    # `set -e` caller — we shouldn't be `set -e` here, but defence in
    # depth) never escapes.
    (
        case "$(uname -s 2>/dev/null || echo unknown)" in
            Darwin)
                # Both known LaunchAgent plists. `launchctl unload` is a
                # no-op-with-warning when the plist doesn't exist; swallow
                # stderr to keep the install log clean.
                local plist
                # Rust LaunchAgent plist.
                plist="$HOME/Library/LaunchAgents/com.trycua.cua-driver-rs.plist"
                if [ -f "$plist" ]; then
                    if [ -f "$plist" ]; then
                        launchctl unload "$plist" >/dev/null 2>&1 || true
                    fi
                fi
                ;;
            Linux)
                # systemctl --user is the only supported supervisor on
                # Linux today (install-local-rust.sh --autostart writes
                # ~/.config/systemd/user/cua-driver-rs.service). `command
                # -v` so we don't error on systemd-less hosts (musl
                # containers, NixOS without user services, etc.).
                if command -v systemctl >/dev/null 2>&1; then
                    systemctl --user stop cua-driver-rs.service >/dev/null 2>&1 || true
                fi
                ;;
            *)
                # Other Unixes (FreeBSD, etc.) — no supervisor we know
                # about, fall through to the pkill backstop.
                ;;
        esac

        # Best-effort: give the supervisor up to ~200ms to take the
        # daemon down before we resort to pkill. Same wait as the
        # PowerShell module after schtasks /End.
        sleep 0.2 2>/dev/null || sleep 1

        if [ "$(uname -s 2>/dev/null || echo unknown)" = "Darwin" ]; then
            # macOS: stop what we can PROVE is Cua Driver (bundle id
            # com.trycua.driver, any path, any version) instead of every
            # process that happens to be named `cua-driver`. Another app can
            # ship its own helper with that name; it is not ours to kill.
            cua_driver_stop_release_processes
        elif command -v pkill >/dev/null 2>&1; then
            # `-x` = exact match on process name so we don't kill a
            # user's `cua-driver-rs-foo` test harness or any script
            # named "cua-driver-something". The Rust + Swift binaries
            # both exec as exactly `cua-driver` so a single pkill
            # covers both.
            pkill -x cua-driver >/dev/null 2>&1 || true
        fi
    ) || true

    return 0
}

# Print a yellow warning if cua-driver processes are still running after
# stop_cua_driver_daemons did its best. On macOS/Linux this almost never
# fires for processes the current user owns — `pkill` succeeds against
# user-owned processes without elevation — so when it DOES fire it
# usually means:
#
#   * Another user on the same host has their own cua-driver running
#     (multi-user dev box). Their daemon is fine; ours just won't see
#     the swap until they restart theirs.
#   * The daemon was spawned with a custom signal handler that ignores
#     SIGTERM (we don't ship such a handler — but a debugger session
#     could install one).
#   * Process is in uninterruptible state (D-state on Linux from a
#     stuck syscall — rare for a userspace daemon).
#
# Mirrors Show-CuaDriverDaemonSurvivors on the PowerShell side, but the
# Unix-side mitigation is different: there's no clean User Account
# Control / High-IL escalation analogue, so the hint is just `sudo
# pkill` (root can reach other users' processes).
#
# Idempotent — safe to call even when stop_cua_driver_daemons did
# clean up everything. Prints nothing in the common case.
show_cua_driver_daemon_survivors() {
    if [ "$(uname -s 2>/dev/null || echo unknown)" = "Darwin" ]; then
        # A stop request starts short-lived cua-driver processes of its own (the
        # CLI re-executes itself); give them a moment before calling them
        # survivors.
        local mac_survivors waited=0 limit=$(( ${CUA_DRIVER_STOP_TIMEOUT:-5} * 2 ))
        while :; do
            mac_survivors=$(cua_driver_release_processes | awk -F '\t' '{ printf "%s%s", sep, $1; sep = ", " }')
            [ -n "$mac_survivors" ] || return 0
            [ "$waited" -lt "$limit" ] || break
            sleep 0.5 2>/dev/null || sleep 1
            waited=$((waited + 1))
        done
        printf 'Note: Cua Driver process(es) still running after the stop attempt (pid: %s).\n' "$mac_survivors"
        printf '      They ignored SIGTERM and SIGKILL. Log out and back in, or run\n'
        printf '      `kill -9 <pid>` yourself, then re-run this installer.\n'
        return 0
    fi

    # `pgrep -x` matches the exact process name the same way `pkill -x`
    # did above, so the survivor list is exactly what the kill couldn't
    # reach (not random other cua-driver-* binaries).
    if ! command -v pgrep >/dev/null 2>&1; then
        # No pgrep, no way to check. Bail quietly — the install can
        # still succeed; worst case the user notices a stale binary
        # and reboots.
        return 0
    fi

    local survivor_pids
    survivor_pids=$(pgrep -x cua-driver 2>/dev/null || true)
    if [ -z "$survivor_pids" ]; then
        return 0
    fi

    # `tput` may not be available (CI, agent sandboxes without TERM);
    # guard so we don't crash before printing the actual warning. The
    # color is decoration — the text is the load-bearing part.
    local yellow normal
    yellow=$(tput setaf 3 2>/dev/null || true)
    normal=$(tput sgr0 2>/dev/null || true)

    # `wc -w` is portable across BSD and GNU; pgrep prints one pid per
    # line so we'd get the same count from `wc -l`, but `wc -w` is
    # robust to a missing trailing newline.
    local count
    count=$(printf '%s\n' "$survivor_pids" | wc -w | tr -d ' ')
    local pid_csv
    pid_csv=$(printf '%s\n' "$survivor_pids" | tr '\n' ',' | sed 's/,$//' | sed 's/,/, /g')

    printf '%sNote: %s cua-driver process(es) still running after best-effort kill (pid: %s).%s\n' \
        "$yellow" "$count" "$pid_csv" "$normal"
    printf '%s      They are probably owned by another user, or are ignoring SIGTERM.%s\n' \
        "$yellow" "$normal"
    printf '%s      To force-kill (needs root if owned by another user):%s\n' \
        "$yellow" "$normal"
    printf '%s        sudo pkill -9 -x cua-driver%s\n' \
        "$yellow" "$normal"
    printf '%s      Or log out and back in. Until they exit, the OLD binary keeps running.%s\n' \
        "$yellow" "$normal"
    return 0
}

# ---------------------------------------------------------------------------
# macOS: find and stop every Cua Driver process, wherever its app lives
# ---------------------------------------------------------------------------
#
# A Mac can hold several copies of CuaDriver.app (an old release in ~/Downloads,
# one in the Trash, a benchmark folder) and `open -a CuaDriver` may start any of
# them. A daemon from such a copy is not the file we are about to replace, so
# neither the pid file nor the install path finds it. We therefore identify
# processes by what they are: an executable named cua-driver inside an app
# bundle whose CFBundleIdentifier is com.trycua.driver, owned by this user.
# Other users' processes (ps -U <uid>) and other apps (a different bundle id,
# CuaDriverLocal's com.trycua.driver.local included) are never touched.

CUA_DRIVER_RELEASE_BUNDLE_ID="com.trycua.driver"

# Value of a top-level string key in an Info.plist. PlistBuddy reads binary and
# XML plists; the awk fallback reads XML plists, so test fixtures and hosts
# without PlistBuddy work too.
cua_driver_plist_string() {
    local plist="$1" key="$2" value=""
    [ -f "$plist" ] || return 1
    if [ -x /usr/libexec/PlistBuddy ]; then
        value="$(/usr/libexec/PlistBuddy -c "Print :$key" "$plist" 2>/dev/null)" || value=""
    fi
    if [ -z "$value" ]; then
        value="$(awk -v key="$key" '
            function text(line) { sub(".*<string>", "", line); sub("</string>.*", "", line); return line }
            index($0, "<key>" key "</key>") {
                if ($0 ~ /<string>/) { print text($0); exit }
                want = 1; next
            }
            want && /<string>/ { print text($0); exit }
            want && /<key>/ { exit }
        ' "$plist" 2>/dev/null)" || value=""
    fi
    [ -n "$value" ] || return 1
    printf '%s' "$value"
}

# The .app directory when "$1" (a process command line) runs a cua-driver
# executable inside an app bundle. Paths with spaces are fine: we cut at the
# fixed /Contents/MacOS/cua-driver suffix, not at the first space.
cua_driver_bundle_of_command() {
    local command_line="$1" bundle
    case "$command_line" in
        */Contents/MacOS/cua-driver|*/Contents/MacOS/cua-driver\ *) ;;
        *) return 1 ;;
    esac
    bundle="${command_line%%/Contents/MacOS/cua-driver*}"
    case "$bundle" in
        /*.app) printf '%s' "$bundle" ;;
        *) return 1 ;;
    esac
}

# True when the bundle is a Cua Driver release app. The bundle's own Info.plist
# decides. If it cannot be read (the app was deleted while its daemon kept
# running) only the stock names CuaDriver.app / CuaDriver-<version>.app count.
cua_driver_bundle_is_release() {
    local bundle="$1" id=""
    id="$(cua_driver_plist_string "$bundle/Contents/Info.plist" CFBundleIdentifier)" || id=""
    if [ -n "$id" ]; then
        [ "$id" = "$CUA_DRIVER_RELEASE_BUNDLE_ID" ]
        return
    fi
    case "${bundle##*/}" in
        CuaDriver.app|CuaDriver-*.app|"CuaDriver "*.app) return 0 ;;
        *) return 1 ;;
    esac
}

# This shell and every parent: an installer started by `cua-driver update` or by
# an agent that runs under a cua-driver process must not stop its own caller.
cua_driver_ancestor_pids() {
    local pid="$$" depth=0 parent
    while [ -n "$pid" ] && [ "$pid" -gt 1 ] 2>/dev/null && [ "$depth" -lt 32 ]; do
        printf '%s\n' "$pid"
        parent="$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d '[:space:]')" || break
        [ -n "$parent" ] || break
        pid="$parent"
        depth=$((depth + 1))
    done
}

# One "<pid><TAB><bundle dir>" line per running Cua Driver process of this user.
cua_driver_release_processes() {
    local uid ancestors line pid command_line bundle
    uid="$(id -u 2>/dev/null)" || return 0
    command -v ps >/dev/null 2>&1 || return 0
    ancestors="$(cua_driver_ancestor_pids)"
    ps -U "$uid" -ww -o pid= -o command= 2>/dev/null | while IFS= read -r line; do
        line="${line#"${line%%[![:space:]]*}"}"
        pid="${line%%[[:space:]]*}"
        case "$pid" in ''|*[!0-9]*) continue ;; esac
        command_line="${line#"$pid"}"
        command_line="${command_line#"${command_line%%[![:space:]]*}"}"
        printf '%s\n' "$ancestors" | grep -qx "$pid" && continue
        bundle="$(cua_driver_bundle_of_command "$command_line")" || continue
        cua_driver_bundle_is_release "$bundle" || continue
        printf '%s\t%s\n' "$pid" "$bundle"
    done
}

# The bundle dir if "$1" is STILL a Cua Driver process (guards against pid reuse
# between listing and signalling).
cua_driver_pid_release_bundle() {
    local command_line bundle
    command_line="$(ps -ww -o command= -p "$1" 2>/dev/null)" || return 1
    command_line="${command_line#"${command_line%%[![:space:]]*}"}"
    bundle="$(cua_driver_bundle_of_command "$command_line")" || return 1
    cua_driver_bundle_is_release "$bundle" || return 1
    printf '%s' "$bundle"
}

# Wait up to $2 seconds for pid $1 to exit.
cua_driver_wait_gone() {
    local pid="$1" tenths=$(( ${2:-5} * 10 ))
    while kill -0 "$pid" 2>/dev/null; do
        [ "$tenths" -gt 0 ] || return 1
        sleep 0.1 2>/dev/null || sleep 1
        tenths=$((tenths - 1))
    done
    return 0
}

# Run a command, giving up (and killing it) after $1 seconds. Output is dropped.
cua_driver_run_bounded() {
    local limit="$1" child tenths
    shift
    "$@" >/dev/null 2>&1 &
    child=$!
    tenths=$((limit * 10))
    while kill -0 "$child" 2>/dev/null && [ "$tenths" -gt 0 ]; do
        sleep 0.1 2>/dev/null || sleep 1
        tenths=$((tenths - 1))
    done
    kill "$child" 2>/dev/null || true
    wait "$child" 2>/dev/null || true
}

# Stop every Cua Driver process of this user, wherever its app lives. Order:
# the daemon's own `stop` request (clean shutdown), then SIGTERM, then SIGKILL,
# each given CUA_DRIVER_STOP_TIMEOUT seconds (default 5). Prints one line per
# process saying how it ended. Returns 1 if any process survived.
cua_driver_stop_release_processes() {
    local timeout="${CUA_DRIVER_STOP_TIMEOUT:-5}" list pid bundle version label how helper tab failed=0
    tab="$(printf '\t')"
    list="$(cua_driver_release_processes)"
    [ -n "$list" ] || return 0
    while IFS="$tab" read -r pid bundle; do
        [ -n "$pid" ] || continue
        version="$(cua_driver_plist_string "$bundle/Contents/Info.plist" CFBundleShortVersionString)" || version=""
        label="pid $pid, ${version:+version $version, }$bundle"
        how=""

        # 1. Ask the daemon to shut down through its own bundle's CLI. Old
        #    releases do not know --expected-pid and simply fail; that is fine.
        helper="$bundle/Contents/MacOS/cua-driver"
        if [ -x "$helper" ] && cua_driver_pid_release_bundle "$pid" >/dev/null; then
            cua_driver_run_bounded "$timeout" "$helper" --expected-pid "$pid" stop
            if cua_driver_wait_gone "$pid" 1; then
                how="a graceful stop request"
            fi
        fi
        # 2. SIGTERM, re-checking the pid still belongs to Cua Driver.
        if [ -z "$how" ] && cua_driver_pid_release_bundle "$pid" >/dev/null; then
            kill -TERM "$pid" 2>/dev/null || true
            if cua_driver_wait_gone "$pid" "$timeout"; then
                how="SIGTERM"
            fi
        fi
        # 3. SIGKILL.
        if [ -z "$how" ] && cua_driver_pid_release_bundle "$pid" >/dev/null; then
            kill -KILL "$pid" 2>/dev/null || true
            if cua_driver_wait_gone "$pid" 2; then
                how="SIGKILL after it ignored SIGTERM for ${timeout}s"
            fi
        fi
        if [ -z "$how" ] && ! kill -0 "$pid" 2>/dev/null; then
            how="its own exit"
        fi
        if [ -n "$how" ]; then
            printf '==> stopped Cua Driver (%s) with %s\n' "$label" "$how"
        else
            printf '==> could not stop Cua Driver (%s); it is still running\n' "$label" >&2
            failed=1
        fi
    done <<EOF
$list
EOF
    return "$failed"
}

# ---------------------------------------------------------------------------
# macOS: make LaunchServices forget every other copy of the app
# ---------------------------------------------------------------------------
#
# `open -a CuaDriver`, a bundle-id lookup and System Settings' permission rows
# all resolve to whichever registered copy macOS likes best, which is how an old
# copy in the Trash became the "CuaDriver-0.34.0" row. After an install only the
# installed bundle should stay registered. `lsregister -u` removes the
# registration only; no file is deleted.

# Where lsregister lives. CUA_DRIVER_LSREGISTER overrides it (tests).
cua_driver_lsregister_path() {
    printf '%s' "${CUA_DRIVER_LSREGISTER:-/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister}"
}

# Paths of every bundle with the given id that LaunchServices (lsregister -dump)
# or Spotlight (mdfind) knows about, one per line, sorted and unique. The dump
# is slow on a busy Mac (tens of seconds), so it is capped by
# CUA_DRIVER_LSREGISTER_TIMEOUT seconds (default 120).
cua_driver_known_bundle_paths() {
    local bundle_id="${1:-$CUA_DRIVER_RELEASE_BUNDLE_ID}" lsregister dump pid waited=0 limit
    lsregister="$(cua_driver_lsregister_path)"
    limit="${CUA_DRIVER_LSREGISTER_TIMEOUT:-120}"
    {
        if [ -x "$lsregister" ]; then
            dump="$(mktemp -t cua-lsdump.XXXXXX 2>/dev/null)" || dump=""
            if [ -n "$dump" ]; then
                "$lsregister" -dump >"$dump" 2>/dev/null &
                pid=$!
                while kill -0 "$pid" 2>/dev/null; do
                    if [ "$waited" -ge "$limit" ]; then
                        kill "$pid" 2>/dev/null || true
                        break
                    fi
                    sleep 1
                    waited=$((waited + 1))
                done
                wait "$pid" 2>/dev/null || true
                # A dump is a series of blocks split by a line of dashes; each
                # block has "path:" and "identifier:" lines.
                awk -v id="$bundle_id" '
                    function flush() { if (path != "" && matches) print path; path = ""; matches = 0 }
                    /^----------/ { flush(); next }
                    /^path:[ \t]/ {
                        p = $0; sub(/^path:[ \t]+/, "", p); sub(/[ \t]+\(0x[0-9a-fA-F]+\)$/, "", p)
                        path = p; next
                    }
                    /^identifier:[ \t]/ {
                        i = $0; sub(/^identifier:[ \t]+/, "", i); sub(/[ \t]+$/, "", i)
                        matches = (i == id); next
                    }
                    END { flush() }
                ' "$dump"
                rm -f "$dump"
            fi
        fi
        if command -v mdfind >/dev/null 2>&1; then
            mdfind "kMDItemCFBundleIdentifier == '$bundle_id'" 2>/dev/null || true
        fi
    } | sed '/^$/d' | sort -u
}

# unregister_other_cua_driver_copies <installed bundle dir>
# Unregisters every other com.trycua.driver bundle and prints one summary line.
# Best effort: never fails the install, never deletes anything.
unregister_other_cua_driver_copies() {
    local active="$1" lsregister active_real path real found=0 paths word on_disk="" on_disk_count=0
    lsregister="$(cua_driver_lsregister_path)"
    [ -x "$lsregister" ] || return 0
    active_real="$(cd "$active" 2>/dev/null && pwd -P)" || active_real="$active"
    paths="$(cua_driver_known_bundle_paths "$CUA_DRIVER_RELEASE_BUNDLE_ID")"
    [ -n "$paths" ] || return 0
    while IFS= read -r path; do
        [ -n "$path" ] || continue
        real="$path"
        if [ -d "$path" ]; then
            real="$(cd "$path" 2>/dev/null && pwd -P)" || real="$path"
        fi
        if [ "$path" = "$active" ] || [ "$real" = "$active_real" ]; then
            continue
        fi
        found=$((found + 1))
        if ! "$lsregister" -u "$path" >/dev/null 2>&1; then
            printf 'warning: could not unregister the old Cua Driver copy at %s\n' "$path" >&2
        fi
        if [ -d "$path" ]; then
            on_disk_count=$((on_disk_count + 1))
            [ "$on_disk_count" -gt 3 ] || on_disk="${on_disk:+$on_disk, }$path"
        fi
    done <<EOF
$paths
EOF
    [ "$found" -gt 0 ] || return 0
    word="copies"
    [ "$found" -ne 1 ] || word="copy"
    printf 'Found %s old Cua Driver %s; macOS will now only use %s\n' "$found" "$word" "$active"
    if [ "$on_disk_count" -gt 0 ]; then
        [ "$on_disk_count" -le 3 ] || on_disk="$on_disk and $((on_disk_count - 3)) more"
        printf 'Their files were left in place (delete them when you no longer need them): %s\n' "$on_disk"
    fi
    return 0
}