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.

16.2 KB
Raw Blame
#!/usr/bin/env bash
# SPDX-License-Identifier: FSL-1.1-MIT
# Copyright (c) 2026 Cua AI, Inc.

# Names and checks shared by install-local.sh and uninstall-local.sh (Cua
# Spaces Local, CUA-1776). Sourced; no side effects besides the definitions.
#
# THE NAMES BELOW MIRROR `CuaChannel::Local` in
# libs/cua/crates/cua-home/src/channel.rs, which owns them. A shell script
# cannot call that module, so they are written once, here, and
# scripts/tests/install-local-test.sh fails when one stops matching it.
# Nothing else in these scripts spells a Local or a Stable name.

# shellcheck disable=SC2034 # each script uses some of these names

# --- Local (what these scripts install and remove) ---------------------------
LOCAL_BUNDLE_ID="com.trycua.spaces.macos.local"    # CuaChannel::bundle_id
# The id Local's first builds had (CuaChannel::legacy_bundle_id): what the
# installer moves away from and the uninstaller also cleans up.
LOCAL_LEGACY_BUNDLE_ID="com.trycua.spaces.local"   # CuaChannel::legacy_bundle_id
LOCAL_APP_DIR_NAME="Cua Spaces Local.app"          # CuaChannel::app_path
LOCAL_CLI_NAME="cua-local"                         # CuaChannel::cli_name
LOCAL_URL_SCHEME="cua-local"                       # CuaChannel::url_scheme
LOCAL_HOME_DIR_NAME=".cua-local"                   # CuaChannel::home_dir
LOCAL_APP_SUPPORT_DIR_NAME="com.trycua.spaces.macos.local" # CuaChannel::app_support_dir_name
LOCAL_HELPER_LABEL="com.trycua.spaces.local.helper"  # CuaChannel::helper_label
LOCAL_HOST_LABEL="com.trycua.spacesd.host.local"     # CuaChannel::host_label
LOCAL_VOLUME_NAME="Cua Volume Local"               # CuaChannel::volume_name
LOCAL_LUME_BIN_NAME="lume-local"                   # CuaChannel::lume_bin_name
LOCAL_LUME_DIR_NAME=".lume-local"                  # CuaChannel::lume_dir
# CuaChannel::keychain_service(Prod) and (Staging). The sign-in and the device
# key live under these services, one item per account.
LOCAL_KEYCHAIN_SERVICES=("ai.cua.session.local" "ai.cua.session.local.staging")
# What macOS keeps under ~/Library for a bundle id: preferences, caches, web view
# data, cookies and saved window state. `library_leaves ID` prints their paths
# below ~/Library, one per line; every one carries ID whole. The Local id is
# Stable's plus ".local", so none of these names is a Stable one (Stable's are
# the same folders with its own id, which are never listed here).
library_leaves() {
    printf '%s\n' \
        "Preferences/$1.plist" \
        "Caches/$1" \
        "HTTPStorages/$1" \
        "WebKit/$1" \
        "Cookies/$1.binarycookies" \
        "Saved Application State/$1.savedState"
}

# --- Stable (what these scripts must never create, replace or remove) --------
# Only used to refuse a bundle that carries a Stable identity.
STABLE_BUNDLE_ID="com.trycua.spaces.macos"          # also its app support folder name
STABLE_URL_SCHEME="cua"
STABLE_HELPER_LABEL="com.trycua.spaces.helper"
STABLE_APP_PARENT="/Applications"                   # CuaChannel::app_path
STABLE_APP_DIR_NAME="Cua Spaces.app"
STABLE_HOME_DIR_NAME=".cua"                         # CuaChannel::home_dir
STABLE_CLI_NAME="cua"                               # CuaChannel::cli_name
STABLE_LUME_DIR_NAME=".lume"                        # CuaChannel::lume_dir
STABLE_VOLUME_NAME="Cua Volume"                     # CuaChannel::volume_name

PLISTBUDDY=/usr/libexec/PlistBuddy
LSREGISTER="${CUA_LSREGISTER:-/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister}"

BOLD=$(tput bold 2>/dev/null || true)
NORMAL=$(tput sgr0 2>/dev/null || true)
RED=$(tput setaf 1 2>/dev/null || true)
GREEN=$(tput setaf 2 2>/dev/null || true)
BLUE=$(tput setaf 4 2>/dev/null || true)
YELLOW=$(tput setaf 3 2>/dev/null || true)

log() { printf '%s==>%s %s\n' "$BLUE" "$NORMAL" "$*"; }
ok() { printf '%s%s%s\n' "$GREEN" "$*" "$NORMAL"; }
warn() { printf '%swarning: %s%s\n' "$YELLOW" "$*" "$NORMAL" >&2; }
err() { printf '%serror: %s%s\n' "$RED" "$*" "$NORMAL" >&2; }

# A value of a bundle's Info.plist (a key path like CFBundleIdentifier); empty
# and failing when it is not there.
plist_get() { "$PLISTBUDDY" -c "Print :$2" "$1" 2>/dev/null; }

# The bundle identifier of an app bundle, empty when it has none.
bundle_id_of() { plist_get "$1/Contents/Info.plist" CFBundleIdentifier || true; }

# Every URL scheme the bundle registers, one per line.
plist_url_schemes() {
    local plist="$1" i=0 j value
    while plist_get "$plist" "CFBundleURLTypes:$i" >/dev/null; do
        j=0
        while value="$(plist_get "$plist" "CFBundleURLTypes:$i:CFBundleURLSchemes:$j")"; do
            printf '%s\n' "$value"
            j=$((j + 1))
        done
        i=$((i + 1))
    done
}

# Succeeds when `app` is a Cua Spaces Local bundle with the bundle id Local's
# first builds had (com.trycua.spaces.local). The id is compared whole.
is_legacy_local_bundle() {
    local app="$1"
    [ ! -L "$app" ] && [ -f "$app/Contents/Info.plist" ] \
        && [ "$(bundle_id_of "$app")" = "$LOCAL_LEGACY_BUNDLE_ID" ]
}

# Succeeds when `path` is absent or a Cua Spaces Local bundle, the only thing
# these scripts may replace or remove: one with the Local bundle id, or with
# the one Local had before (they move that one to the new id). Anything else, a
# Stable app included, is refused with the reason. Ids are compared whole: the
# Local id is Stable's plus ".local", so a prefix test would take one for the
# other.
require_local_bundle_or_absent() {
    local app="$1" id
    if [ ! -e "$app" ] && [ ! -L "$app" ]; then
        return 0
    fi
    if [ -L "$app" ]; then
        err "refusing to touch $app: it is a symlink, not a Cua Spaces Local bundle"
        return 1
    fi
    if [ ! -f "$app/Contents/Info.plist" ]; then
        err "refusing to touch $app: it is not an app bundle (no Contents/Info.plist)"
        return 1
    fi
    id="$(bundle_id_of "$app")"
    if [ "$id" != "$LOCAL_BUNDLE_ID" ] && [ "$id" != "$LOCAL_LEGACY_BUNDLE_ID" ]; then
        err "refusing to touch $app: its bundle id is '${id:-none}', not $LOCAL_BUNDLE_ID"
        return 1
    fi
    return 0
}

# Stops the running Local app, its helper included, and nothing else: only
# processes started from inside this bundle are matched.
quit_local_app() {
    local app="$1" pattern pids waited=0
    command -v pgrep >/dev/null 2>&1 || return 0
    pattern="^$(printf '%s' "$app" | sed 's/[][\.*^$+?(){}|]/\\&/g')/Contents/"
    pids="$(pgrep -f "$pattern" 2>/dev/null || true)"
    [ -n "$pids" ] || return 0
    log "stopping the running $LOCAL_APP_DIR_NAME"
    # shellcheck disable=SC2086 # one pid per word
    kill $pids 2>/dev/null || true
    while [ "$waited" -lt 10 ] && pgrep -f "$pattern" >/dev/null 2>&1; do
        sleep 0.5
        waited=$((waited + 1))
    done
    pids="$(pgrep -f "$pattern" 2>/dev/null || true)"
    if [ -n "$pids" ]; then
        # shellcheck disable=SC2086
        kill -9 $pids 2>/dev/null || true
    fi
}

# The old Local app's helper login item and processes: the app unregisters its
# own login item (the same call the host setup makes), then it is stopped, and
# the helper job is booted out in case the app could not do it. Nothing but the
# Local helper label is named. `app` must be a Local bundle (checked by the
# caller).
retire_local_app() {
    local app="$1"
    if [ -x "$app/Contents/MacOS/CuaSpacesMac" ]; then
        # A second try, then the state decides: a login item that is not
        # registered or not found is gone, whatever the exit status said.
        CUA_CHANNEL=local "$app/Contents/MacOS/CuaSpacesMac" --service-helper unregister >/dev/null 2>&1 \
            || CUA_CHANNEL=local "$app/Contents/MacOS/CuaSpacesMac" --service-helper unregister >/dev/null 2>&1 \
            || ! local_helper_registered "$app" \
            || warn "the app could not unregister its helper; remove $LOCAL_APP_DIR_NAME from System Settings > Login Items if it stays."
    fi
    quit_local_app "$app"
    launchctl bootout "gui/$(id -u)/$LOCAL_HELPER_LABEL" >/dev/null 2>&1 || true
}

# Removes what the old Local bundle id left under ~/Library: its Application
# Support folder and the files macOS keeps for a bundle id. Every name carries
# the old id whole (and none is a name of the current Local id or of Stable's).
# Prints each path it removed, one per line.
remove_legacy_local_data() {
    local leaf path
    while IFS= read -r leaf; do
        case "$leaf" in
            *"$LOCAL_LEGACY_BUNDLE_ID"*) ;;
            *) continue ;;
        esac
        path="$HOME/Library/$leaf"
        if [ -e "$path" ] || [ -L "$path" ]; then
            rm -rf "$path"
            printf '%s\n' "$path"
        fi
    done < <(printf '%s\n' "Application Support/$LOCAL_LEGACY_BUNDLE_ID"; library_leaves "$LOCAL_LEGACY_BUNDLE_ID")
}

# Succeeds when the Local app at `app` has its helper login item registered
# and enabled (what `--service-helper status` reports).
local_helper_enabled() {
    local app="$1"
    [ -x "$app/Contents/MacOS/CuaSpacesMac" ] || return 1
    CUA_CHANNEL=local "$app/Contents/MacOS/CuaSpacesMac" --service-helper status 2>/dev/null | grep -q '"status":"enabled"'
}

# Succeeds when the helper login item of the Local app at `app` is still
# registered, or waits for approval in System Settings (`--service-helper
# status`). Not registered, not found and no answer are not.
local_helper_registered() {
    local app="$1"
    [ -x "$app/Contents/MacOS/CuaSpacesMac" ] || return 1
    CUA_CHANNEL=local "$app/Contents/MacOS/CuaSpacesMac" --service-helper status 2>/dev/null \
        | grep -Eq '"status":"(enabled|requires-approval)"'
}

# Clears every macOS privacy permission (Screen Recording, Accessibility,
# Automation and the rest: `tccutil reset All`) the Local bundle id holds, for
# the Local app at `app`. `tccutil` resolves a bundle id through LaunchServices
# and fails with "No such bundle identifier" once the app is gone, so this runs
# while the app is still installed, after it is stopped. `id` is the Local id
# (or the old Local id). Best effort; Stable's id is never passed.
reset_local_permissions() {
    local app="$1" id="$2"
    case "$id" in
        "$LOCAL_BUNDLE_ID"|"$LOCAL_LEGACY_BUNDLE_ID") ;;
        *) return 0 ;;
    esac
    if ! command -v tccutil >/dev/null 2>&1; then
        warn "tccutil is missing: remove $LOCAL_APP_DIR_NAME from the Privacy & Security lists in System Settings yourself."
        return 0
    fi
    if [ -x "$LSREGISTER" ] && [ -d "$app" ]; then
        "$LSREGISTER" -f "$app" >/dev/null 2>&1 || true
    fi
    if tccutil reset All "$id" >/dev/null 2>&1; then
        log "reset the macOS permissions of $id (Screen Recording, Accessibility and the rest)"
    else
        warn "could not reset the permissions of $id; run: tccutil reset All $id"
    fi
}

# Registers the helper login item of the Local app at `app` (the app does it
# itself: only a bundle's own code may), best effort. `what` names the app in
# the warning.
register_local_helper() {
    local app="$1" what="$2"
    [ -x "$app/Contents/MacOS/CuaSpacesMac" ] || return 0
    CUA_CHANNEL=local "$app/Contents/MacOS/CuaSpacesMac" --service-helper register >/dev/null 2>&1 \
        || warn "$what's helper login item could not be registered; open the app and set up this Mac again."
}

# Puts back what `retire_local_app` took from an old Local app that is restored
# after a failed install: LaunchServices knows it again and, when `helper_was_enabled`
# is 1, its helper login item is registered again (best effort).
restore_retired_local_app() {
    local app="$1" helper_was_enabled="$2"
    if [ -x "$LSREGISTER" ]; then
        "$LSREGISTER" -f "$app" >/dev/null 2>&1 || true
    fi
    if [ "$helper_was_enabled" = 1 ]; then
        register_local_helper "$app" "the previous app"
    fi
}

# --- Where Local may write -----------------------------------------------------

# The absolute path with `.`, `..` and every symlink resolved, whether or not
# it exists yet (what is missing is taken as written: it cannot be a link).
# Fails on a symlink loop. This is the path an install or removal acts on, so
# a `..` or a link in --prefix cannot hide where it lands.
canonicalize_path() {
    local rest="$1" cur="/" comp next target links=0
    case "$rest" in
        /*) ;;
        *) rest="$PWD/$rest" ;;
    esac
    while :; do
        while [ "${rest#/}" != "$rest" ]; do rest="${rest#/}"; done
        [ -n "$rest" ] || break
        comp="${rest%%/*}"
        if [ "$comp" = "$rest" ]; then rest=""; else rest="${rest#*/}"; fi
        case "$comp" in
            .) continue ;;
            ..) cur="$(dirname "$cur")"; continue ;;
        esac
        next="${cur%/}/$comp"
        if [ -L "$next" ]; then
            links=$((links + 1))
            [ "$links" -le 40 ] || return 1
            target="$(readlink "$next")" || return 1
            case "$target" in
                /*) cur="/" ;;
            esac
            rest="$target/$rest"
            continue
        fi
        cur="$next"
    done
    printf '%s' "$cur"
}

# A path as compared: lower case (the usual macOS volume ignores case) and
# without the firmlink prefix that makes /System/Volumes/Data/Applications the
# same folder as /Applications.
path_key() {
    local key
    key="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')"
    case "$key" in
        /system/volumes/data/*) key="${key#/system/volumes/data}" ;;
    esac
    printf '%s' "$key"
}

# Succeeds when `candidate`, or a folder above it, is the very file system
# object `container` (same device and inode): it is `container` or inside it,
# however the path is spelled.
is_inside_by_identity() {
    local container="$1" candidate="$2" want have
    want="$(stat -f '%d:%i' "$container" 2>/dev/null || true)"
    [ -n "$want" ] || return 1
    while :; do
        have="$(stat -f '%d:%i' "$candidate" 2>/dev/null || true)"
        [ "$have" != "$want" ] || return 0
        [ "$candidate" != "/" ] || return 1
        candidate="$(dirname "$candidate")"
    done
}

# Succeeds when one path is the other or inside it (both given canonical).
paths_overlap() {
    local a b
    a="$(path_key "$1")/"
    b="$(path_key "$2")/"
    case "$a" in "$b"*) return 0 ;; esac
    case "$b" in "$a"*) return 0 ;; esac
    is_inside_by_identity "$1" "$2" && return 0
    is_inside_by_identity "$2" "$1" && return 0
    return 1
}

# What belongs to the released Cua Spaces, one path per line, for the home
# `$1` (canonical): the app, the home, the CLI, Lume's folder, Cua Volume and
# the app's support folder.
stable_owned_paths() {
    local home="$1"
    printf '%s\n' \
        "$STABLE_APP_PARENT/$STABLE_APP_DIR_NAME" \
        "$home/$STABLE_HOME_DIR_NAME" \
        "$home/.local/bin/$STABLE_CLI_NAME" \
        "$home/$STABLE_LUME_DIR_NAME" \
        "$home/$STABLE_VOLUME_NAME" \
        "$home/Library/Application Support/$STABLE_BUNDLE_ID"
}

# Fails, saying why, when `path` (canonical; `label` names it) is or is inside
# anything the released Cua Spaces owns, or inside /Applications, where
# Cua Spaces Local never goes. Each owned path is resolved the same way as
# `path` before they are compared, and checked as written too: ~/.lume may be a
# symlink to /Volumes/VMs, and then /Volumes/VMs is the Stable Lume folder.
# (The identity check below uses lstat, so it cannot see through a link itself.)
reject_stable_overlap() {
    local label="$1" path="$2" home owned resolved
    home="$(canonicalize_path "$HOME")" || { err "cannot resolve HOME ($HOME)"; return 1; }
    while IFS= read -r owned; do
        resolved="$(canonicalize_path "$owned")" || { err "refusing: cannot resolve $owned (a symlink loop?), which belongs to the released Cua Spaces."; return 1; }
        if paths_overlap "$path" "$owned" || paths_overlap "$path" "$resolved"; then
            if [ "$resolved" != "$owned" ]; then owned="$owned (a link to $resolved)"; fi
            err "refusing: the $label path $path is, or is inside, $owned, which belongs to the released Cua Spaces. Pick another --prefix."
            return 1
        fi
    done < <(stable_owned_paths "$home")
    resolved="$(canonicalize_path "$STABLE_APP_PARENT")" || resolved="$STABLE_APP_PARENT"
    if paths_overlap "$path" "$STABLE_APP_PARENT" || paths_overlap "$path" "$resolved"; then
        err "refusing: the $label path $path is inside $STABLE_APP_PARENT, where the released Cua Spaces lives. Cua Spaces Local goes under ~/Applications; pick another --prefix."
        return 1
    fi
}