install

#!/usr/bin/env bash
set -euo pipefail

PRODUCT="OpenAlice CLI"
REPOSITORY="TraderAlice/OpenAlice"
PUBLIC_INSTALLER_URL="https://openalice.ai/install"
DOWNLOAD_BASE_URL="${OPENALICE_DOWNLOAD_BASE_URL:-https://download.openalice.ai}"
RELEASES_API_URL="${OPENALICE_RELEASES_API_URL:-https://api.github.com/repos/${REPOSITORY}/releases/latest}"
RELEASE_ASSET_BASE_URL="${OPENALICE_RELEASE_ASSET_BASE_URL:-https://github.com/${REPOSITORY}/releases/download}"
BETA_MANIFEST_URL="${OPENALICE_BETA_MANIFEST_URL:-${DOWNLOAD_BASE_URL}/beta/manifest.json}"
LEGACY_STABLE_VERSION="0.90.1"
LEGACY_STABLE_INSTALLER_URL="${OPENALICE_LEGACY_STABLE_INSTALLER_URL:-${RELEASE_ASSET_BASE_URL}/v${LEGACY_STABLE_VERSION}/OpenAlice-${LEGACY_STABLE_VERSION}-install}"
LEGACY_STABLE_INSTALLER_SHA256="${OPENALICE_LEGACY_STABLE_INSTALLER_SHA256:-a2f34a715cc4a089854fde18741e316953868c1685db592b67b2b4ea10ede0bb}"
INSTALL_DIR="${OPENALICE_INSTALL_DIR:-$HOME/.openalice}"
INSTALLER_URL="${OPENALICE_INSTALL_URL:-}"
KEEP_RELEASES="${OPENALICE_INSTALL_KEEP_RELEASES:-3}"

channel="stable"
channel_set=false
exact_version=""
legacy_branch=""
selector_kind=""
selector_value=""
archive_path=""
archive_sha256=""
plan_only=false
assume_yes=false
modify_path=true

fail() {
  printf 'openalice installer: %s\n' "$*" >&2
  exit 1
}

usage() {
  cat <<'EOF'
OpenAlice CLI Installer

Usage: install [options]

Options:
  --channel <name>        Follow stable, beta, or dev (default: stable)
  --version <x.y.z>       Install an exact release; alone it remains pinned
  --branch <master|dev>   Compatibility alias for stable or dev
  --archive <path>        Install a local Bun release archive
  --sha256 <hex>          Required checksum for --archive
  --install-dir <path>    Install root (default: ~/.openalice)
  --no-modify-path        Do not edit a shell profile
  --plan                  Show the transaction without changing files
  -y, --yes               Approve non-interactively
  -h, --help              Show this help

The CLI installer manages OpenAlice release artifacts only. It does not install,
update, pin, or remove Pi, OpenCode, Codex, Claude Code, or another Agent Runtime.
EOF
}

while [[ $# -gt 0 ]]; do
  case "$1" in
    --channel)
      [[ $# -ge 2 ]] || fail "--channel requires a value"
      [[ -z "$archive_path" ]] || fail "--channel cannot be combined with --archive"
      [[ "$channel_set" == false ]] || fail "Specify --channel only once"
      case "$2" in
        stable|beta|dev) channel="$2" ;;
        *) fail "--channel must be stable, beta, or dev" ;;
      esac
      channel_set=true
      shift 2
      ;;
    --branch)
      [[ $# -ge 2 ]] || fail "--branch requires a value"
      [[ -z "$archive_path" ]] || fail "--branch cannot be combined with --archive"
      [[ "$channel_set" == false ]] || fail "Use only one of --channel or --branch"
      case "$2" in
        master) channel="stable" ;;
        dev) channel="dev" ;;
        *) fail "Bun preview installs support only --branch master or --branch dev" ;;
      esac
      channel_set=true
      legacy_branch="$2"
      shift 2
      ;;
    --version)
      [[ $# -ge 2 ]] || fail "--version requires a value"
      [[ -z "$archive_path" ]] || fail "--version cannot be combined with --archive"
      [[ -z "$exact_version" ]] || fail "Specify --version only once"
      exact_version="${2#v}"
      [[ "$exact_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$ ]] \
        || fail "--version must be an OpenAlice release version such as 0.91.0"
      shift 2
      ;;
    --archive)
      [[ $# -ge 2 ]] || fail "--archive requires a path"
      [[ -z "$archive_path" && -z "$exact_version" && "$channel_set" == false ]] \
        || fail "--archive cannot be combined with --channel, --branch, or --version"
      archive_path="$2"
      shift 2
      ;;
    --sha256)
      [[ $# -ge 2 ]] || fail "--sha256 requires a value"
      archive_sha256="$2"
      shift 2
      ;;
    --install-dir)
      [[ $# -ge 2 ]] || fail "--install-dir requires a path"
      INSTALL_DIR="$2"
      shift 2
      ;;
    --no-modify-path) modify_path=false; shift ;;
    --plan) plan_only=true; shift ;;
    -y|--yes) assume_yes=true; shift ;;
    -h|--help) usage; exit 0 ;;
    *) fail "Unknown option: $1" ;;
  esac
done

if [[ -n "$archive_path" ]]; then
  selector_kind="local"
  selector_value="local"
elif [[ -n "$exact_version" ]]; then
  [[ -z "$legacy_branch" ]] \
    || fail "--branch cannot be combined with --version; use --channel to retain an update channel"
  if [[ "$channel_set" == true ]]; then
    if [[ "$channel" == stable ]]; then
      [[ "$exact_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] \
        || fail "--channel stable requires a stable --version"
    elif [[ "$channel" == beta ]]; then
      [[ "$exact_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+-beta(\.[1-9][0-9]*)?$ ]] \
        || fail "--channel beta requires a beta --version"
    else
      fail "--channel dev cannot be combined with --version"
    fi
    selector_kind="release"
  else
    selector_kind="pinned"
  fi
  selector_value="$exact_version"
else
  case "$channel" in
    stable) selector_kind="stable"; selector_value="latest" ;;
    beta) selector_kind="beta"; selector_value="latest" ;;
    dev) selector_kind="development"; selector_value="dev" ;;
  esac
fi

[[ "$INSTALL_DIR" == /* ]] || INSTALL_DIR="$PWD/${INSTALL_DIR#./}"
[[ "$KEEP_RELEASES" =~ ^[1-9][0-9]*$ ]] || fail "OPENALICE_INSTALL_KEEP_RELEASES must be a positive integer"
[[ "$INSTALL_DIR" != *$'\n'* && "$INSTALL_DIR" != *$'\r'* ]] || fail "--install-dir must not contain a newline"

if [[ -z "$INSTALLER_URL" ]]; then
  if [[ "$legacy_branch" == dev ]]; then
    INSTALLER_URL="https://raw.githubusercontent.com/${REPOSITORY}/dev/install"
  else
    INSTALLER_URL="$PUBLIC_INSTALLER_URL"
  fi
fi
case "$INSTALLER_URL" in
  http://*|https://*) ;;
  *) fail "OPENALICE_INSTALL_URL must be an HTTP(S) URL" ;;
esac
[[ "$INSTALLER_URL" != *'"'* && "$INSTALLER_URL" != *'\\'* \
  && "$INSTALLER_URL" != *$'\n'* && "$INSTALLER_URL" != *$'\r'* ]] \
  || fail "OPENALICE_INSTALL_URL contains unsupported characters"

raw_os="$(uname -s)"
case "$raw_os" in
  Darwin*) platform="darwin" ;;
  Linux*) platform="linux" ;;
  *) fail "Unsupported OS: $raw_os. The Bun CLI currently supports macOS and Linux." ;;
esac
raw_arch="$(uname -m)"
case "$raw_arch" in
  arm64|aarch64) architecture="arm64" ;;
  x86_64|amd64) architecture="x64" ;;
  *) fail "Unsupported architecture: $raw_arch" ;;
esac
if [[ "$platform" == darwin && "$architecture" == x64 ]]; then
  if [[ "$(sysctl -n sysctl.proc_translated 2>/dev/null || printf 0)" == 1 ]]; then
    architecture="arm64"
  fi
fi

command -v tar >/dev/null 2>&1 || fail "tar is required"
if command -v sha256sum >/dev/null 2>&1; then
  hash_file() { sha256sum "$1" | awk '{print $1}'; }
elif command -v shasum >/dev/null 2>&1; then
  hash_file() { shasum -a 256 "$1" | awk '{print $1}'; }
else
  fail "sha256sum or shasum is required"
fi

delegate_legacy_stable_install() {
  local legacy_update_channel="${1:-stable}"
  local temporary legacy_installer actual_sha256 legacy_status
  local -a legacy_args
  case "$legacy_update_channel" in
    stable|pinned) ;;
    *) fail "Internal error: invalid legacy stable update channel $legacy_update_channel" ;;
  esac
  if [[ -e "$INSTALL_DIR/cli" || -L "$INSTALL_DIR/cli" ]]; then
    fail "OpenAlice ${LEGACY_STABLE_VERSION} uses the legacy Node-managed layout and cannot safely replace a native CLI installation. Stay on beta/dev until a native stable release is available."
  fi
  [[ "$LEGACY_STABLE_INSTALLER_SHA256" =~ ^[a-f0-9]{64}$ ]] \
    || fail "Legacy stable installer checksum is invalid"
  temporary="$(mktemp -d "${TMPDIR:-/tmp}/openalice-legacy-installer.XXXXXX")"
  legacy_installer="$temporary/install"
  if ! curl -fL --retry 2 --connect-timeout 10 --max-time 60 \
    -o "$legacy_installer" "$LEGACY_STABLE_INSTALLER_URL"; then
    rm -rf "$temporary"
    fail "Could not download the verified OpenAlice ${LEGACY_STABLE_VERSION} installer"
  fi
  actual_sha256="$(hash_file "$legacy_installer")"
  if [[ "$actual_sha256" != "$LEGACY_STABLE_INSTALLER_SHA256" ]]; then
    rm -rf "$temporary"
    fail "OpenAlice ${LEGACY_STABLE_VERSION} installer failed SHA-256 verification"
  fi
  legacy_args=(--install-dir "$INSTALL_DIR")
  [[ "$modify_path" == true ]] || legacy_args+=(--no-modify-path)
  [[ "$plan_only" == true ]] && legacy_args+=(--plan)
  [[ "$assume_yes" == true ]] && legacy_args+=(--yes)
  legacy_status=0
  OPENALICE_INSTALL_URL="$INSTALLER_URL" \
    OPENALICE_INSTALLER_RELEASE_VERSION="$LEGACY_STABLE_VERSION" \
    OPENALICE_INSTALL_UPDATE_CHANNEL="$legacy_update_channel" \
    OPENALICE_INSTALLER_UPDATE_CHANNEL="$legacy_update_channel" \
    bash "$legacy_installer" "${legacy_args[@]}" \
    || legacy_status=$?
  rm -rf "$temporary"
  exit "$legacy_status"
}

release_version=""
artifact_url=""
if [[ -n "$archive_path" ]]; then
  [[ -f "$archive_path" ]] || fail "Archive not found: $archive_path"
  [[ "$archive_sha256" =~ ^[a-f0-9]{64}$ ]] || fail "--archive requires --sha256 with 64 lowercase hex characters"
  artifact_source="$archive_path"
else
  command -v curl >/dev/null 2>&1 || fail "curl is required for a network install"
  if [[ "$selector_kind" == stable ]]; then
    latest_json="$(curl -fsSL --max-time 15 "$RELEASES_API_URL")" \
      || fail "Could not resolve the latest OpenAlice release"
    release_version="$(printf '%s' "$latest_json" | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"v\{0,1\}\([^"]*\)".*/\1/p' | head -n 1)"
    [[ "$release_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] \
      || fail "Latest release metadata did not contain a valid version"
    if [[ "$release_version" == "$LEGACY_STABLE_VERSION" ]]; then
      delegate_legacy_stable_install stable
    fi
    artifact_url="${RELEASE_ASSET_BASE_URL}/v${release_version}/openalice-cli-${release_version}-${platform}-${architecture}.tar.gz"
  elif [[ "$selector_kind" == beta ]]; then
    beta_json="$(curl -fsSL --max-time 15 "$BETA_MANIFEST_URL")" \
      || fail "Could not resolve the latest OpenAlice beta"
    release_version="$(printf '%s' "$beta_json" | sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1)"
    [[ "$release_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+-beta(\.[1-9][0-9]*)?$ ]] \
      || fail "Beta manifest did not contain a valid beta version"
    artifact_url="${RELEASE_ASSET_BASE_URL}/v${release_version}/openalice-cli-${release_version}-${platform}-${architecture}.tar.gz"
  elif [[ "$selector_kind" == pinned || "$selector_kind" == release ]]; then
    release_version="$selector_value"
    if [[ "$release_version" == "$LEGACY_STABLE_VERSION" ]]; then
      if [[ "$selector_kind" == pinned ]]; then
        delegate_legacy_stable_install pinned
      else
        delegate_legacy_stable_install stable
      fi
    fi
    artifact_url="${RELEASE_ASSET_BASE_URL}/v${release_version}/openalice-cli-${release_version}-${platform}-${architecture}.tar.gz"
  else
    artifact_url="${DOWNLOAD_BASE_URL}/cli/dev/openalice-cli-dev-${platform}-${architecture}.tar.gz"
  fi
  checksum_url="${artifact_url}.sha256"
  checksum_text="$(curl -fsSL --max-time 15 "$checksum_url")" \
    || fail "Could not download the release checksum: $checksum_url"
  archive_sha256="$(printf '%s' "$checksum_text" | awk 'NR == 1 { print $1 }')"
  [[ "$archive_sha256" =~ ^[a-f0-9]{64}$ ]] || fail "Release checksum metadata is invalid"
  artifact_source="$artifact_url"
fi
[[ -z "${OPENALICE_EXPECTED_CLI_ARTIFACT_SHA256:-}" || "$archive_sha256" == "$OPENALICE_EXPECTED_CLI_ARTIFACT_SHA256" ]] \
  || fail "Release checksum $archive_sha256 does not match expected $OPENALICE_EXPECTED_CLI_ARTIFACT_SHA256"

action="Install"
legacy_cli_root="$INSTALL_DIR/cli-versions"
legacy_detected=false
if [[ -d "$legacy_cli_root" ]]; then
  legacy_detected=true
fi
if [[ -L "$INSTALL_DIR/cli/current" ]]; then
  action="Update"
  if [[ "$legacy_detected" == true ]]; then
    action="Update and remove legacy CLI"
  fi
elif [[ "$legacy_detected" == true ]]; then
  action="Replace legacy CLI"
fi
cat <<EOF
$PRODUCT install plan

Action          $action
Channel         $selector_kind ($selector_value)
Platform        $platform-$architecture
Artifact        $artifact_source
SHA-256         $archive_sha256
Install root    $INSTALL_DIR
Active pointer  $INSTALL_DIR/cli/current
Command         $INSTALL_DIR/bin/openalice
Retention       $KEEP_RELEASES releases (including the active release)
Legacy cutover  $legacy_detected

OpenAlice manages: the native CLI release, release-owned Git, launch shims,
activation pointer, provenance, installer lock, and PATH entry.
OpenAlice does not manage: Agent Runtime executables, their versions,
credentials, native configuration, or user data.
EOF

if [[ "$plan_only" == true ]]; then
  printf '\nPlan complete. No files were changed.\n'
  exit 0
fi

if [[ "$assume_yes" != true ]]; then
  if ! { exec 3<>/dev/tty; } 2>/dev/null; then
    printf 'No interactive terminal is available. Review --plan, then re-run with --yes.\n' >&2
    exit 2
  fi
  printf '\nContinue with this install? [y/N] ' >&3
  IFS= read -r answer <&3 || answer=""
  exec 3>&- 3<&-
  [[ "$answer" =~ ^[Yy]([Ee][Ss])?$ ]] || { printf '\nNo changes made.\n'; exit 0; }
fi

cli_root="$INSTALL_DIR/cli"
releases_dir="$cli_root/releases"
provenance_dir="$cli_root/provenance"
activation_path="$cli_root/activation.json"
bin_dir="$INSTALL_DIR/bin"
lock_dir="$INSTALL_DIR/.cli-install.lock"
staging_dir=""
lock_owned=false
previous_release_name=""
activation_receipt_written=false
activation_switched=false
install_complete=false
legacy_launcher_backup=""
legacy_launchers_backed_up=false

cleanup() {
  cleanup_status=$?
  trap - EXIT INT TERM HUP
  if [[ "$cleanup_status" -ne 0 && "$install_complete" != true ]]; then
    set +e
    if [[ "$activation_receipt_written" == true ]]; then
      rollback_restored=true
      if [[ "$activation_switched" == true ]]; then
        if [[ -n "$previous_release_name" ]]; then
          rollback_link="$cli_root/current.rollback.$$"
          rm -f "$rollback_link"
          if ! ln -s "releases/$previous_release_name" "$rollback_link"; then
            rollback_restored=false
          elif [[ "$platform" == darwin ]]; then
            mv -fh "$rollback_link" "$cli_root/current" || rollback_restored=false
          else
            mv -Tf "$rollback_link" "$cli_root/current" || rollback_restored=false
          fi
        else
          rm -f "$cli_root/current" || rollback_restored=false
        fi
      fi
      if [[ "$rollback_restored" == true ]]; then
        rollback_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
        activation_next="$activation_path.next.$$"
        cat >"$activation_next" <<EOF
{
  "schemaVersion": 1,
  "activeRelease": "$release_name",
  "previousRelease": $([[ -n "$previous_release_name" ]] && printf '"%s"' "$previous_release_name" || printf 'null'),
  "productVersion": "$artifact_version",
  "state": "rolled_back",
  "activatedAt": "$activated_at",
  "rolledBackAt": "$rollback_at",
  "failureCode": "EINSTALL"
}
EOF
        chmod 600 "$activation_next" && mv -f "$activation_next" "$activation_path" \
          || printf 'Warning: restored the previous release but could not record rollback metadata.\n' >&2
      else
        printf 'Warning: automatic restoration of the previous OpenAlice release failed; inspect %s before retrying.\n' "$cli_root/current" >&2
      fi
      [[ -z "${rollback_link:-}" ]] || rm -f "$rollback_link"
    fi
    if [[ "$legacy_launchers_backed_up" == true ]]; then
      launcher_restore_ok=true
      for launcher_name in openalice alice alice-workspace alice-uta traderhub pi pi.cmd openalice.cmd; do
        rm -f "$bin_dir/$launcher_name" || launcher_restore_ok=false
        if [[ -e "$legacy_launcher_backup/$launcher_name" || -L "$legacy_launcher_backup/$launcher_name" ]]; then
          mv "$legacy_launcher_backup/$launcher_name" "$bin_dir/$launcher_name" \
            || launcher_restore_ok=false
        fi
      done
      if [[ "$launcher_restore_ok" != true ]]; then
        printf 'Warning: automatic restoration of one or more legacy OpenAlice launchers failed; inspect %s before retrying.\n' "$bin_dir" >&2
      fi
    fi
    set -e
  fi
  [[ -z "$staging_dir" ]] || rm -rf "$staging_dir"
  if [[ "$lock_owned" == true ]]; then rm -rf "$lock_dir"; fi
  exit "$cleanup_status"
}
trap cleanup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
trap 'exit 129' HUP

mkdir -p "$INSTALL_DIR"
if [[ -d "$lock_dir" ]]; then
  lock_pid="$(cat "$lock_dir/pid" 2>/dev/null || true)"
  if [[ "$lock_pid" =~ ^[1-9][0-9]*$ ]] && kill -0 "$lock_pid" 2>/dev/null; then
    fail "Another OpenAlice CLI installer is running (pid $lock_pid)"
  fi
  printf 'Removing a stale CLI installer lock.\n'
  rm -rf "$lock_dir"
fi
mkdir "$lock_dir"
printf '%s\n' "$$" >"$lock_dir/pid"
lock_owned=true
mkdir -p "$releases_dir" "$provenance_dir" "$bin_dir" "$cli_root/staging"
releases_dir="$(CDPATH= cd -- "$releases_dir" && pwd -P)"
staging_dir="$(mktemp -d "$cli_root/staging/install.XXXXXX")"
downloaded_archive="$staging_dir/release.tar.gz"

if [[ -n "$archive_path" ]]; then
  cp "$archive_path" "$downloaded_archive"
else
  printf '\nDownloading OpenAlice for %s-%s...\n' "$platform" "$architecture"
  curl -fL --retry 2 --connect-timeout 10 --max-time 300 -o "$downloaded_archive" "$artifact_url"
fi
actual_sha256="$(hash_file "$downloaded_archive")"
[[ "$actual_sha256" == "$archive_sha256" ]] \
  || fail "Downloaded archive failed SHA-256 verification (expected $archive_sha256, got $actual_sha256)"

archive_root=""
while IFS= read -r archive_entry; do
  archive_entry="${archive_entry#./}"
  case "$archive_entry" in
    /*|../*|*/../*|*/..) fail "Archive contains an unsafe path: $archive_entry" ;;
  esac
  entry_root="${archive_entry%%/*}"
  [[ -n "$entry_root" ]] || continue
  if [[ -z "$archive_root" ]]; then archive_root="$entry_root"; fi
  [[ "$entry_root" == "$archive_root" ]] || fail "Archive contains multiple top-level entries"
done < <(tar -tzf "$downloaded_archive")
[[ "$archive_root" == openalice-cli-* ]] || fail "Archive root is not an OpenAlice CLI release"

unpack_dir="$staging_dir/unpack"
mkdir "$unpack_dir"
tar -xzf "$downloaded_archive" -C "$unpack_dir"
candidate="$(find "$unpack_dir" -mindepth 1 -maxdepth 1 -type d -name 'openalice-cli-*' -print -quit)"
[[ -n "$candidate" ]] || fail "Archive did not contain one OpenAlice CLI release directory"
[[ "$(find "$unpack_dir" -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ')" == 1 ]] \
  || fail "Archive contained multiple top-level directories"
release_json="$candidate/release.json"
executable="$candidate/bin/openalice"
[[ -f "$release_json" && -x "$executable" && -f "$candidate/share/openalice/ui/dist/index.html" ]] \
  || fail "Archive is missing the executable, release metadata, or Web UI"

json_field() {
  sed -n "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" "$1" | head -n 1
}
artifact_version="$(json_field "$release_json" version)"
artifact_platform="$(json_field "$release_json" platform)"
artifact_arch="$(json_field "$release_json" arch)"
content_identity="$(json_field "$release_json" contentIdentity)"
[[ "$artifact_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$ ]] || fail "release.json has an invalid version"
[[ "$artifact_platform" == "$platform" && "$artifact_arch" == "$architecture" ]] \
  || fail "Archive target $artifact_platform-$artifact_arch does not match $platform-$architecture"
[[ "$content_identity" =~ ^[a-f0-9]{16}$ ]] || fail "release.json has an invalid content identity"
[[ -z "${OPENALICE_EXPECTED_CLI_CONTENT_IDENTITY:-}" || "$content_identity" == "$OPENALICE_EXPECTED_CLI_CONTENT_IDENTITY" ]] \
  || fail "Archive content identity $content_identity does not match expected $OPENALICE_EXPECTED_CLI_CONTENT_IDENTITY"
[[ -z "$release_version" || "$artifact_version" == "$release_version" ]] \
  || fail "Archive version $artifact_version does not match requested $release_version"
[[ -z "${OPENALICE_EXPECTED_CLI_VERSION:-}" || "$artifact_version" == "$OPENALICE_EXPECTED_CLI_VERSION" ]] \
  || fail "Archive contains $artifact_version instead of expected release $OPENALICE_EXPECTED_CLI_VERSION"

reported_version="$(OPENALICE_APP_HOME="$candidate/share/openalice" "$executable" --version)"
[[ "$reported_version" == "$artifact_version" ]] \
  || fail "Executable reports $reported_version but release.json reports $artifact_version"

tree_metadata() {
  local root="$1" path relative entry_type entry_mode link_target
  while IFS= read -r -d '' path; do
    relative="${path#"$root"}"
    relative="${relative#/}"
    [[ -n "$relative" ]] || relative="."
    link_target=""
    if [[ -L "$path" ]]; then
      entry_type="link"
      entry_mode="-"
      link_target="$(readlink "$path")"
    elif [[ -d "$path" ]]; then
      entry_type="directory"
      if [[ "$platform" == darwin ]]; then
        entry_mode="$(stat -f '%Lp' "$path")"
      else
        entry_mode="$(stat -c '%a' "$path")"
      fi
    elif [[ -f "$path" ]]; then
      entry_type="file"
      if [[ "$platform" == darwin ]]; then
        entry_mode="$(stat -f '%Lp' "$path")"
      else
        entry_mode="$(stat -c '%a' "$path")"
      fi
    else
      entry_type="other"
      entry_mode="-"
    fi
    printf '%s\t%s\t%s\t%s\n' "$relative" "$entry_type" "$entry_mode" "$link_target"
  done < <(find "$root" -print0)
}

release_name="${artifact_version}-${platform}-${architecture}-${content_identity}"
final_release="$releases_dir/$release_name"
if [[ -e "$final_release" ]]; then
  [[ -d "$final_release" && ! -L "$final_release" ]] \
    || fail "Existing release $release_name is damaged; preserve it and reinstall after inspection"
  command -v diff >/dev/null 2>&1 \
    || fail "diff is required to verify the existing OpenAlice release"
  diff -qr "$candidate" "$final_release" >/dev/null \
    || fail "Existing release $release_name is damaged; preserve it and reinstall after inspection"
  diff -u \
    <(tree_metadata "$candidate" | LC_ALL=C sort) \
    <(tree_metadata "$final_release" | LC_ALL=C sort) >/dev/null \
    || fail "Existing release $release_name is damaged; preserve it and reinstall after inspection"
  printf 'Reusing verified release %s.\n' "$release_name"
else
  mv "$candidate" "$final_release"
fi

case "$selector_kind" in
  stable) update_channel="stable"; selector_json_kind="version"; selector_json_value="v$artifact_version" ;;
  beta) update_channel="beta"; selector_json_kind="version"; selector_json_value="v$artifact_version" ;;
  release) update_channel="$channel"; selector_json_kind="version"; selector_json_value="v$artifact_version" ;;
  pinned) update_channel="pinned"; selector_json_kind="version"; selector_json_value="v$artifact_version" ;;
  development) update_channel="development"; selector_json_kind="branch"; selector_json_value="dev" ;;
  local) update_channel="custom"; selector_json_kind="version"; selector_json_value="local-$artifact_version" ;;
esac
cat >"$provenance_dir/$release_name.json" <<EOF
{
  "schemaVersion": 3,
  "repository": "$REPOSITORY",
  "cliVersion": "$artifact_version",
  "selector": { "kind": "$selector_json_kind", "value": "$selector_json_value" },
  "installerUrl": "$INSTALLER_URL",
  "updateChannel": "$update_channel",
  "method": "direct",
  "artifact": { "platform": "$platform", "arch": "$architecture", "sha256": "$archive_sha256" },
  "installedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
}
EOF

if [[ -L "$cli_root/current" ]]; then
  previous_release_path="$(CDPATH= cd -- "$cli_root/current" && pwd -P)"
  canonical_releases_dir="$(CDPATH= cd -- "$releases_dir" && pwd -P)"
  [[ "$(dirname "$previous_release_path")" == "$canonical_releases_dir" ]] \
    || fail "The active OpenAlice release pointer leaves the installer-owned releases directory"
  previous_release_name="$(basename "$previous_release_path")"
  [[ "$previous_release_name" =~ ^[A-Za-z0-9._+-]+$ ]] \
    || fail "The active OpenAlice release name is invalid"
fi

if [[ "$legacy_detected" == true ]]; then
  legacy_launcher_backup="$staging_dir/legacy-launchers"
  mkdir "$legacy_launcher_backup"
  for launcher_name in openalice alice alice-workspace alice-uta traderhub pi pi.cmd openalice.cmd; do
    launcher_path="$bin_dir/$launcher_name"
    if [[ -e "$launcher_path" || -L "$launcher_path" ]]; then
      [[ -f "$launcher_path" || -L "$launcher_path" ]] \
        || fail "Legacy launcher path is not a regular file or symlink and cannot be replaced safely: $launcher_path"
    fi
  done
  for launcher_name in openalice alice alice-workspace alice-uta traderhub pi pi.cmd openalice.cmd; do
    launcher_path="$bin_dir/$launcher_name"
    if [[ -e "$launcher_path" || -L "$launcher_path" ]]; then
      cp -pP "$launcher_path" "$legacy_launcher_backup/$launcher_name"
    fi
  done
  legacy_launchers_backed_up=true
fi

if [[ "$previous_release_name" != "$release_name" ]]; then
  activated_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
  activation_next="$activation_path.next.$$"
  cat >"$activation_next" <<EOF
{
  "schemaVersion": 1,
  "activeRelease": "$release_name",
  "previousRelease": $([[ -n "$previous_release_name" ]] && printf '"%s"' "$previous_release_name" || printf 'null'),
  "productVersion": "$artifact_version",
  "state": "pending",
  "activatedAt": "$activated_at"
}
EOF
  chmod 600 "$activation_next"
  mv -f "$activation_next" "$activation_path"
  activation_receipt_written=true

  next_link="$cli_root/current.next.$$"
  rm -f "$next_link"
  ln -s "releases/$release_name" "$next_link"
  if [[ "$platform" == darwin ]]; then
    mv -fh "$next_link" "$cli_root/current"
  else
    mv -Tf "$next_link" "$cli_root/current"
  fi
  activation_switched=true
fi

write_launcher() {
  launcher_name="$1"
  workspace_cli="${2:-}"
  temporary_launcher="$bin_dir/.${launcher_name}.next.$$"
  cat >"$temporary_launcher" <<EOF
#!/bin/sh
set -eu
bin_dir=\$(CDPATH= cd -- "\$(dirname -- "\$0")" && pwd -P)
install_root=\$(dirname "\$bin_dir")
release_dir=\$(CDPATH= cd -- "\$install_root/cli/current" && pwd -P)
release_name=\$(basename "\$release_dir")
content_identity=\${release_name##*-}
export OPENALICE_INSTALL_ROOT="\$install_root"
export OPENALICE_RELEASE_DIR="\$release_dir"
export OPENALICE_INSTALL_SOURCE="\$install_root/cli/provenance/\$release_name.json"
export OPENALICE_CONTENT_IDENTITY="\$content_identity"
export OPENALICE_INSTALL_METHOD="direct"
EOF
  if [[ -n "$workspace_cli" ]]; then
    printf 'exec "$release_dir/bin/openalice" --workspace-cli %s "$@"\n' "$workspace_cli" >>"$temporary_launcher"
  else
    printf 'exec "$release_dir/bin/openalice" "$@"\n' >>"$temporary_launcher"
  fi
  chmod 755 "$temporary_launcher"
  mv -f "$temporary_launcher" "$bin_dir/$launcher_name"
}

write_launcher openalice
for helper in alice alice-workspace alice-uta traderhub; do write_launcher "$helper" "$helper"; done
"$bin_dir/openalice" --version >/dev/null

if [[ "$legacy_detected" == true ]]; then
  rm -f "$bin_dir/pi" "$bin_dir/pi.cmd" "$bin_dir/openalice.cmd"
  rm -rf "$legacy_cli_root"
  printf 'Removed the validated legacy CLI release and managed-Pi launchers.\n'
fi
install_complete=true

active_release="$(CDPATH= cd -- "$cli_root/current" && pwd -P)"
release_paths=("$releases_dir"/*)
if [[ -e "${release_paths[0]}" ]]; then
  release_count=0
  while IFS= read -r retained_release; do
    [[ -n "$retained_release" ]] || continue
    release_count=$((release_count + 1))
    if (( release_count > KEEP_RELEASES )) \
      && [[ "$retained_release" != "$active_release" ]] \
      && [[ -z "$previous_release_name" || "$retained_release" != "$releases_dir/$previous_release_name" ]]; then
      retained_name="$(basename "$retained_release")"
      rm -rf "$retained_release"
      rm -f "$provenance_dir/$retained_name.json"
    fi
  done < <(ls -1dt "${release_paths[@]}")
fi

BEGIN_MARKER="# >>> OpenAlice CLI >>>"
END_MARKER="# <<< OpenAlice CLI <<<"
shell_single_quote() {
  local quoted
  quoted="$(printf '%s' "$1" | sed "s/'/'\\\\''/g")"
  printf "'%s'" "$quoted"
}
quoted_bin_dir="$(shell_single_quote "$bin_dir")"
path_command="export PATH=${quoted_bin_dir}:\$PATH"
profile=""
case "$(basename "${SHELL:-}")" in
  zsh) [[ "$platform" == darwin ]] && profile="$HOME/.zprofile" || profile="$HOME/.zshrc" ;;
  bash) [[ "$platform" == darwin ]] && profile="$HOME/.bash_profile" || profile="$HOME/.bashrc" ;;
  fish) profile="$HOME/.config/fish/config.fish"; path_command="fish_add_path -- ${quoted_bin_dir}" ;;
esac
if [[ "$modify_path" == true && -n "$profile" ]]; then
  mkdir -p "$(dirname "$profile")"
  touch "$profile"
  if ! grep -Fq "$BEGIN_MARKER" "$profile"; then
    printf '\n%s\n%s\n%s\n' "$BEGIN_MARKER" "$path_command" "$END_MARKER" >>"$profile" \
      || printf 'Warning: could not update %s; use the activation command below.\n' "$profile" >&2
  fi
fi

printf '\nOpenAlice %s is ready.\n' "$artifact_version"
printf 'Active release: %s\n' "$final_release"
if [[ ":${PATH:-}:" != *":$bin_dir:"* ]]; then
  printf 'Activate OpenAlice in this terminal now (no restart required):\n  %s\n' "$path_command"
fi
printf 'Run: openalice\n'
printf 'Agent Runtimes remain user-owned and are discovered from PATH.\n'