@cats-inc/cats-platform 0.2.8 → 0.3.4

package/scripts/linux/provider-cli-common.sh

@@ -4,6 +4,7 @@ if [ -n "${CATS_PLATFORM_UNIX_PROVIDER_COMMON_SH:-}" ]; then
   return 0 2>/dev/null || exit 0
 fi
 readonly CATS_PLATFORM_UNIX_PROVIDER_COMMON_SH=1
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/provider-version-common.sh"
 
 json_escape() {
   local value="$1"
@@ -343,7 +344,7 @@ run_downloaded_shell_installer() {
   local installer_path status=0
 
   installer_path="$(mktemp)"
-  if ! curl -fsSL "$url" -o "$installer_path"; then
+  if ! curl -fsSL --connect-timeout 10 --max-time 60 "$url" -o "$installer_path"; then
     rm -f "$installer_path"
     printf 'Failed to download the installer from %s\n' "$url" >&2
     return 1
@@ -411,26 +412,8 @@ run_remote_pipe_installer() {
   url="$(provider_install_url "$provider")"
 
   case "$provider" in
-    antigravity|grok)
-      curl -fsSL "$url" | bash
-      ;;
-    goose)
-      curl -fsSL "$url" | env CONFIGURE=false bash
-      ;;
-    muse)
-      # Download first, then run: with `curl ... | bash` a failed download still
-      # exits 0, because bash reads empty input and succeeds.
-      run_downloaded_shell_installer "$url"
-      ;;
-    cursor)
-      curl "$url" -fsSL | bash
-      ;;
-    claude|junie)
-      curl -fsSL "$url" | bash
-      ;;
-    *)
-      return 1
-      ;;
+    goose) CONFIGURE=false run_downloaded_shell_installer "$url" ;;
+    *) run_downloaded_shell_installer "$url" ;;
   esac
 }
 
@@ -457,20 +440,14 @@ run_kiro_installer() {
   local installer_path
 
   installer_path="$(mktemp)"
-  curl -fsSL "$(provider_install_url kiro)" -o "$installer_path"
+  curl -fsSL --connect-timeout 10 --max-time 60 "$(provider_install_url kiro)" -o "$installer_path" || { rm -f "$installer_path"; return 1; }
   chmod +x "$installer_path"
 
-  if [ "$mode" = 'reinstall' ]; then
-    rm -f "$HOME/.local/bin/kiro-cli" "$HOME/.local/bin/kiro-cli-chat" "$HOME/.local/bin/kiro-cli-term"
-    if [ "$platform" = 'macos' ]; then
-      rm -rf '/Applications/Kiro CLI.app'
-      rm -f "$HOME/.local/bin/bash (kiro-cli-term)" "$HOME/.local/bin/fish (kiro-cli-term)" \
-        "$HOME/.local/bin/nu (kiro-cli-term)" "$HOME/.local/bin/zsh (kiro-cli-term)"
-    fi
-  fi
 
-  bash "$installer_path" --force < /dev/null
+  local install_status=0
+  bash "$installer_path" --force < /dev/null || install_status=$?
   rm -f "$installer_path"
+  [ "$install_status" -eq 0 ] || return "$install_status"
 
   if [ "$platform" = 'macos' ]; then
     ensure_kiro_cli_symlink_macos
@@ -485,15 +462,17 @@ run_provider_install_action() {
 
   case "$provider" in
     antigravity)
-      if [ "$action" = 'upgrade' ]; then
-        rm -f "$HOME/.local/bin/agy" || true
-        run_remote_pipe_installer "$provider"
-      elif [ "$action" = 'force' ]; then
-        rm -f "$HOME/.local/bin/agy" || true
-        run_remote_pipe_installer "$provider"
-      else
-        run_remote_pipe_installer "$provider"
+      local backup='' result=0 destination="$HOME/.local/bin/agy"
+      if { [ "$action" = upgrade ] || [ "$action" = force ]; } && [ -f "$destination" ] && [ ! -L "$destination" ]; then
+        backup="$(mktemp)" || return 1
+        cp -p "$destination" "$backup" || { rm -f "$backup"; return 1; }
+        rm -f "$destination" || { rm -f "$backup"; return 1; }
       fi
+      run_remote_pipe_installer "$provider" || result=$?
+      [ -x "$destination" ] || result=1
+      if [ "$result" -ne 0 ] && [ -n "$backup" ]; then cp -p "$backup" "$destination" || true; fi
+      [ -z "$backup" ] || rm -f "$backup"
+      return "$result"
       ;;
     grok)
       run_remote_pipe_installer "$provider"
@@ -508,7 +487,7 @@ run_provider_install_action() {
       ;;
     claude)
       if [ "$action" = 'upgrade' ] && current_command="$(detect_provider_command "$platform" "$provider")"; then
-        "$current_command" update || true
+        "$current_command" update
       else
         run_remote_pipe_installer "$provider"
       fi
@@ -986,76 +965,72 @@ run_native_provider_installer() {
     return 0
   fi
 
-  printf 'Installing %s...\n' "$display_name"
-  if [ "$force" = 'true' ]; then
-    run_provider_install_action "$platform" "$provider" 'force'
-  elif [ "$upgrade" = 'true' ]; then
-    run_provider_install_action "$platform" "$provider" 'upgrade'
-  else
-    run_provider_install_action "$platform" "$provider" 'install'
+  local before_version="$detected_version" latest='' version_state=unknown
+  local install_status=0 attempted=true final_installed=false observed_change=unchanged
+  if [ "$upgrade" = true ] && [ "$force" = false ] && [ "$initial_installed" = true ]; then
+    latest="$(cats_native_latest_version "$provider")"
+    version_state="$(cats_native_version_state "$provider" "$detected_version" "$latest")"
+    if [ "$version_state" = current ]; then
+      attempted=false
+      planned_actions=()
+    elif [ -z "$latest" ] && [ "$provider" != claude ] && [ "$provider" != muse ]; then
+      warnings+=('Could not compare the published version; the official installer will verify the update.')
+    fi
   fi
-  applied_changes=("${planned_actions[@]}")
-
-  ensure_provider_bin_path_export "$shell_rc" "$provider"
-  ensure_provider_alias "$shell_rc" "$provider"
-
-  while [ $attempt -le 3 ]; do
+  if [ "$attempted" = true ]; then
+    printf 'Installing %s...\n' "$display_name" >&2
+    if [ "$force" = true ]; then
+      run_provider_install_action "$platform" "$provider" force || install_status=$?
+    elif [ "$upgrade" = true ]; then
+      run_provider_install_action "$platform" "$provider" upgrade || install_status=$?
+    else
+      run_provider_install_action "$platform" "$provider" install || install_status=$?
+    fi
+  fi
+  hash -r
+  if [ "$install_status" -eq 0 ]; then
+    ensure_provider_bin_path_export "$shell_rc" "$provider"
+    ensure_provider_alias "$shell_rc" "$provider"
+  fi
+  for attempt in 1 2 3; do
     if command_path="$(detect_provider_command "$platform" "$provider")"; then
+      final_installed=true
       detected_version="$(provider_version_line "$command_path" "$provider")"
-      if [ "$emit_json" = 'true' ]; then
-        warnings=("Reload your shell if ${display_name} is not visible yet: source ${shell_rc}")
-        printf '{'
-        printf '"helper":"%s-%s-native-installer",' "$platform" "$provider"
-        printf '"mode":"%s",' "$execution_mode"
-        printf '"status":"ready",'
-        printf '"installed":true,'
-        printf '"commandPath":"%s",' "$(json_escape "$command_path")"
-        printf '"detectedVersion":"%s",' "$(json_escape "$detected_version")"
-        printf '"plannedActions":'
-        json_string_array "${planned_actions[@]}"
-        printf ','
-        printf '"appliedChanges":'
-        json_string_array "${applied_changes[@]}"
-        printf ','
-        printf '"warnings":'
-        json_string_array "${warnings[@]}"
-        printf ','
-        printf '"manualSteps":'
-        json_string_array "$(provider_manual_steps "$provider")"
-        printf ','
-        printf '"interruptions":[]'
-        printf '}\n'
-      else
-        printf '%s ready: %s\n' "$display_name" "$detected_version"
-        printf 'Reload your shell if %s is not visible yet: source %s\n' "$display_name" "$shell_rc"
-      fi
-      return 0
+      break
     fi
-
+    [ "$install_status" -eq 0 ] && [ "$attempted" = true ] || break
     sleep 2
-    attempt=$((attempt + 1))
   done
-
-  if [ "$emit_json" = 'true' ]; then
-    printf '{'
-    printf '"helper":"%s-%s-native-installer",' "$platform" "$provider"
-    printf '"mode":"%s",' "$execution_mode"
-    printf '"status":"failed",'
-    printf '"installed":false,'
-    printf '"commandPath":null,'
-    printf '"detectedVersion":null,'
-    printf '"plannedActions":'
-    json_string_array "${planned_actions[@]}"
-    printf ','
-    printf '"appliedChanges":'
-    json_string_array "${applied_changes[@]}"
-    printf ','
-    printf '"warnings":[],'
-    printf '"manualSteps":[],'
-    printf '"interruptions":[]'
-    printf '}\n'
-    return 1
+  local final_status=ready
+  if [ "$install_status" -ne 0 ] || [ "$final_installed" = false ]; then
+    final_status=failed
+    observed_change=failed
+    warnings+=("Installer or verification failed (exit $install_status); any previous installation is shown separately.")
+  elif [ "$attempted" = false ]; then observed_change=unchanged
+  elif [ "$initial_installed" = false ]; then observed_change=installed
+  elif [ -n "$before_version" ] && [ -n "$detected_version" ] && [ "$before_version" != "$detected_version" ]; then
+    case "$(cats_version_compare "$(cats_native_version_token "$provider" "$detected_version")" "$(cats_native_version_token "$provider" "$before_version")")" in
+      1) observed_change=upgraded ;; -1) observed_change=downgraded ;; *) observed_change=version_changed ;;
+    esac
+  else observed_change=unchanged; fi
+  if [ "$final_status" = ready ] && { [ "$upgrade" = true ] || [ "$force" = true ]; }; then
+    cats_cleanup_native_versions "$provider" "$detected_version" || true
   fi
-  printf 'Failed to verify %s after install.\n' "$display_name" >&2
-  return 1
+  case "$observed_change" in
+    installed|upgraded|downgraded|version_changed) applied_changes=("${observed_change}_${provider}_installation") ;;
+  esac
+  if [ "$emit_json" = true ]; then
+    printf '{"helper":"%s-%s-native-installer","mode":"%s","status":"%s",' "$platform" "$provider" "$execution_mode" "$final_status"
+    printf '"installed":%s,"commandPath":"%s","detectedVersion":"%s",' "$final_installed" "$(json_escape "$command_path")" "$(json_escape "$detected_version")"
+    printf '"previousVersion":"%s","observedChange":"%s",' "$(json_escape "$before_version")" "$observed_change"
+    printf '"summary":"%s: %s -> %s",' "$observed_change" "$(json_escape "$before_version")" "$(json_escape "$detected_version")"
+    printf '"plannedActions":'; json_string_array "${planned_actions[@]}"
+    printf ',"appliedChanges":'; json_string_array "${applied_changes[@]}"
+    printf ',"warnings":'; json_string_array "${warnings[@]}"
+    printf ',"manualSteps":'; json_string_array "$(provider_manual_steps "$provider")"
+    printf ',"interruptions":[]}\n'
+  else
+    printf '%s %s: %s -> %s\n' "$display_name" "$observed_change" "$before_version" "$detected_version"
+  fi
+  [ "$final_status" = ready ]
 }

package/scripts/linux/provider-version-common.sh

@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# Source this file for passive native version comparison and bounded vendor queries.
+# Usage: source provider-version-common.sh; cats_native_latest_version <provider>
+# Adapted from environment-bootstrap shared/posix/upstream-version.sh at 752dc13.
+# Queries return an empty value on failure; check-only mode never invokes them.
+cats_version_token() {
+    printf '%s' "$1" | tr -d '\r' | grep -oE '[0-9]+(\.[0-9]+)+(-[0-9A-Za-z]+(\.[0-9A-Za-z]+)*|\.[A-Za-z][0-9A-Za-z]*(\.[0-9]+)*)?' | head -n 1 || true
+}
+
+# cats_version_compare <a> <b>
+# 只比數字段、補滿四段：印 -1（a 較舊）、0、1（a 較新）；任一邊解析不出版本印空字串。
+# 空字串要當成「無法比較、交回原本流程」，不能當成落後，否則查不到版本時每次都會重裝。
+cats_version_compare() {
+    local a b i x y
+    a="$(printf '%s' "$1" | tr -d '\r' | grep -oE '[0-9]+(\.[0-9]+)*' | head -n 1 || true)"
+    b="$(printf '%s' "$2" | tr -d '\r' | grep -oE '[0-9]+(\.[0-9]+)*' | head -n 1 || true)"
+    if [ -z "$a" ] || [ -z "$b" ]; then
+        printf ''
+        return 0
+    fi
+
+    i=1
+    while [ "$i" -le 4 ]; do
+        x="$(printf '%s' "$a" | awk -F. -v n="$i" '{print $n}')"
+        y="$(printf '%s' "$b" | awk -F. -v n="$i" '{print $n}')"
+        [ -n "$x" ] || x=0
+        [ -n "$y" ] || y=0
+        if [ "$((10#$x))" -lt "$((10#$y))" ]; then printf -- '-1'; return 0; fi
+        if [ "$((10#$x))" -gt "$((10#$y))" ]; then printf '1'; return 0; fi
+        i=$((i + 1))
+    done
+    printf '0'
+}
+
+# _cats_json_string_field <field> ：從 stdin 的 JSON 文字撈第一個 "field":"value" 的 value
+_cats_json_string_field() {
+    grep -oE "\"$1\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" | head -n 1 | sed -E 's/.*"([^"]*)"$/\1/'
+}
+
+# cats_github_latest_release <owner/repo>
+# GitHub Releases 的最新穩定版 tag（去掉開頭的 v）；失敗印空。
+cats_github_latest_release() {
+    local json
+    json="$(curl -fsSL --connect-timeout 5 --max-time 20 -H 'Accept: application/vnd.github+json' "https://api.github.com/repos/$1/releases/latest" 2>/dev/null)" || return 0
+    printf '%s' "$json" | _cats_json_string_field tag_name | sed 's/^v//' || true
+}
+
+# cats_antigravity_latest_version [已下載的官方 install.sh]
+# 官方腳本讀的是 $DOWNLOAD_BASE_URL/manifests/<platform>.json 的 version。
+# 傳入抓下來的腳本可以順便從裡面撈 base URL，官方搬家時就不必改這裡；撈不到用寫死的。
+# platform 的算法照抄官方（darwin_arm64 / linux_amd64 / linux_amd64_musl …）。
+cats_antigravity_latest_version() {
+    local base='https://antigravity-cli-auto-updater-974169037036.us-central1.run.app'
+    local found os arch platform
+
+    if [ -n "${1:-}" ] && [ -r "$1" ]; then
+        found="$(grep -oE 'DOWNLOAD_BASE_URL="https://[^"]+"' "$1" | head -n 1 | sed -E 's/^DOWNLOAD_BASE_URL="(.*)"$/\1/')"
+        [ -n "$found" ] && base="$found"
+    fi
+
+    case "$(uname -s)" in
+        Darwin) os=darwin ;;
+        Linux)  os=linux ;;
+        *) return 0 ;;
+    esac
+    case "$(uname -m)" in
+        x86_64|amd64)  arch=amd64 ;;
+        arm64|aarch64) arch=arm64 ;;
+        *) return 0 ;;
+    esac
+    if [ "$os" = linux ] && { [ -f /lib/libc.musl-x86_64.so.1 ] || [ -f /lib/libc.musl-aarch64.so.1 ] || ldd /bin/ls 2>&1 | grep -q musl; }; then
+        platform="linux_${arch}_musl"
+    else
+        platform="${os}_${arch}"
+    fi
+
+    curl -fsSL --connect-timeout 5 --max-time 20 "$base/manifests/$platform.json" 2>/dev/null | _cats_json_string_field version || true
+}
+
+# cats_cursor_agent_latest_version <已下載的官方 install 腳本>
+# 官方 https://cursor.com/install 是支寫死版本的腳本，目錄名就是版本
+# （…/versions/2026.09.10-fd3934a）。版本是「日期-commit」，cats_version_compare 只比得到
+# 日期，同日不同 commit 由呼叫端用字串相等另判。
+cats_cursor_agent_latest_version() {
+    [ -n "${1:-}" ] && [ -r "$1" ] || return 0
+    grep -oE 'versions/[0-9]{4}\.[0-9]{2}\.[0-9]{2}-[0-9A-Za-z]+' "$1" | head -n 1 | sed 's#^versions/##' || true
+}
+
+# cats_junie_latest_build
+# 官方 install.sh 讀 GitHub raw 的 update-info.jsonl：一行一個 build，version 是 build 號
+# （3110.7，也是 versions/ 底下的目錄名）、marketing 才是 26.9.7、platform 是
+# linux-amd64 / macos-aarch64 這種。印本平台最大的 build 號；失敗印空。
+cats_junie_latest_build() {
+    local os arch platform jsonl line v best=''
+
+    case "$(uname -s)" in
+        Darwin) os=macos ;;
+        Linux)  os=linux ;;
+        *) return 0 ;;
+    esac
+    case "$(uname -m)" in
+        x86_64|amd64)  arch=amd64 ;;
+        arm64|aarch64) arch=aarch64 ;;
+        *) return 0 ;;
+    esac
+    platform="${os}-${arch}"
+
+    jsonl="$(curl -fsSL --connect-timeout 5 --max-time 20 'https://raw.githubusercontent.com/jetbrains-junie/junie/main/update-info.jsonl' 2>/dev/null)" || return 0
+
+    while IFS= read -r line; do
+        case "$line" in
+            *"\"platform\":\"$platform\""*) ;;
+            *) continue ;;
+        esac
+        v="$(printf '%s' "$line" | _cats_json_string_field version || true)"
+        [ -n "$v" ] || continue
+        if [ -z "$best" ] || [ "$(cats_version_compare "$v" "$best")" = "1" ]; then
+            best="$v"
+        fi
+    done <<< "$jsonl"
+
+    printf '%s' "$best"
+}
+
+# cats_kiro_latest_version
+# Kiro 的官方 installer 讀 stable/latest/manifest.json（Windows 版 Install-KiroCLI.ps1
+# 用的是同一份），欄位 version。
+cats_kiro_latest_version() {
+    curl -fsSL --connect-timeout 5 --max-time 20 'https://prod.download.cli.kiro.dev/stable/latest/manifest.json' 2>/dev/null | _cats_json_string_field version || true
+}
+
+# cats_devin_latest_version
+# Devin 的官方 install.sh 與 Windows 版 setup.ps1 讀的都是 cli/current/manifest.json，欄位
+# version（3000.10.27）。官方腳本同版雖不重抓，POSIX 版仍會重建兩個符號連結、Windows 版更會
+# 無條件重寫 180 MB 的 devin.exe；先問這裡，同版就完全不動。
+cats_devin_latest_version() {
+    curl -fsSL --connect-timeout 5 --max-time 20 'https://static.devin.ai/cli/current/manifest.json' 2>/dev/null | _cats_json_string_field version || true
+}
+
+# cats_grok_latest_version [channel]
+# Grok 的官方 install.sh（與 Windows 的 install.ps1）決定要下載哪一版，靠的只是一個純文字端點：
+# https://x.ai/cli/<channel>（Cloudflare 前端）不通就退到 GCS 上的同名檔案，內容就是版本號
+# （1.0.30）。這裡照抄同一套順序；channel 預設跟官方一樣吃 GROK_CHANNEL（stable）。
+# 三平台都問這裡，刻意不用 `grok update --check --json`：那要執行 grok 本體去連 x.ai 做 TLS
+# 交握，而 grok 的 TLS 實作用到 SHA-512 硬體指令（sha512su0），沒有這個擴充的 aarch64
+# （Raspberry Pi 4/5 的 Cortex-A72/A76）會當場 SIGILL、輸出全空 —— 見 CLAUDE.md Known Gotchas。
+# 這個端點不必執行任何工具，問到的也正是安裝器接下來會抓的版本。失敗印空。
+cats_grok_latest_version() {
+    local channel="${1:-${GROK_CHANNEL:-stable}}" url v
+    for url in "https://x.ai/cli/${channel}" "https://storage.googleapis.com/grok-build-public-artifacts/cli/${channel}"; do
+        v="$(curl -fsSL --connect-timeout 5 --max-time 20 "$url" 2>/dev/null | tr -d '\r' | head -n 1 | tr -d '[:space:]' || true)"
+        if printf '%s' "$v" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9._]+)?$'; then
+            printf '%s' "$v"
+            return 0
+        fi
+    done
+    printf ''
+}
+
+
+cats_native_latest_version() {
+  local script
+  case "$1" in
+    antigravity) cats_antigravity_latest_version ;;
+    cursor)
+      script="$(curl -fsSL --connect-timeout 5 --max-time 20 https://cursor.com/install 2>/dev/null)" || return 0
+      printf '%s' "$script" | grep -oE 'versions/[0-9]{4}\.[0-9]{2}\.[0-9]{2}-[0-9A-Za-z]+' | head -n 1 | sed 's#^versions/##' || true
+      ;;
+    goose) cats_github_latest_release aaif-goose/goose ;;
+    junie) cats_junie_latest_build ;;
+    kiro) cats_kiro_latest_version ;;
+    devin) cats_devin_latest_version ;;
+    grok) cats_grok_latest_version ;;
+    *) return 0 ;;
+  esac
+}
+
+cats_native_version_token() {
+  if [ "$1" = junie ]; then
+    printf '%s' "$2" | sed -nE 's/.*\(([0-9]+(\.[0-9]+)+)\).*/\1/p' | head -n 1 || true
+  else
+    cats_version_token "$2"
+  fi
+}
+
+# Print current/older/unknown; Cursor same-day hashes are distinct releases.
+cats_native_version_state() {
+  local current latest comparison
+  current="$(cats_native_version_token "$1" "$2")"
+  latest="$3"
+  [ -n "$current" ] && [ -n "$latest" ] || { printf unknown; return 0; }
+  comparison="$(cats_version_compare "$current" "$latest")"
+  if [ "$comparison" = 1 ] || { [ "$comparison" = 0 ] && { [ "$1" != cursor ] || [ "$current" = "$latest" ]; }; }; then
+    printf current
+  elif [ -n "$comparison" ]; then printf older
+  else printf unknown; fi
+}
+
+# Delete only older numeric version directories in a known installer-owned tree.
+# Current/pending/newer builds, symlinks and custom locations outside HOME remain.
+cats_cleanup_native_versions() {
+  local provider="$1" version="$2" root='' data='' keep='' actual='' directory='' name='' ancestor=''
+  keep="$(cats_native_version_token "$provider" "$version")"
+  [ -n "$keep" ] || return 0
+  case "$provider" in
+    cursor)
+      root="$HOME/.local/share/cursor-agent/versions"
+      [ -L "$HOME/.local/bin/cursor-agent" ] || return 0
+      actual="$(readlink "$HOME/.local/bin/cursor-agent")" || return 0
+      [ "$(basename "$(dirname "$actual")")" = "$keep" ] || return 0
+      ;;
+    devin)
+      root="${XDG_DATA_HOME:-$HOME/.local/share}/devin/cli/_versions"
+      [ -L "$root/current" ] || return 0
+      actual="$(readlink "$root/current")" || return 0
+      [ "$(basename "$actual")" = "$keep" ] || return 0
+      ;;
+    junie)
+      data="${JUNIE_DATA_DIR:-$HOME/.local/share/junie}"
+      root="$data/versions"
+      [ ! -e "$data/updates/pending-update.json" ] && [ -L "$data/current" ] || return 0
+      actual="$(readlink "$data/current")" || return 0
+      [ "$(basename "$actual")" = "$keep" ] || return 0
+      ;;
+    *) return 0 ;;
+  esac
+  case "$root" in "$HOME"/*) ;; *) return 0 ;; esac
+  [ -d "$root" ] || return 0
+  ancestor="$root"
+  while [ "$ancestor" != / ] && [ "$ancestor" != . ]; do
+    [ ! -L "$ancestor" ] || return 0
+    ancestor="$(dirname "$ancestor")"
+  done
+  local canonical_home
+  canonical_home="$(cd -P -- "$HOME" && pwd -P)" || return 0
+  root="$(cd -P -- "$root" && pwd -P)" || return 0
+  case "$root" in "$canonical_home"/*) ;; *) return 0 ;; esac
+  for directory in "$root"/*; do
+    [ -d "$directory" ] && [ ! -L "$directory" ] || continue
+    name="$(basename "$directory")"
+    printf '%s' "$name" | grep -qE '^[0-9]+(\.[0-9]+)+(-[0-9A-Za-z]+)?$' || continue
+    [ "$(cats_version_compare "$name" "$keep")" = -1 ] || continue
+    # Skip directory trees with links rather than recurse through an unknown layout.
+    [ -z "$(find "$directory" -type l -print 2>/dev/null)" ] || continue
+    rm -rf -- "$directory" || printf 'Could not remove old %s build %s.\n' "$provider" "$name" >&2
+  done
+}

package/scripts/linux/test-linux-package-smoke.sh

@@ -66,6 +66,8 @@ assert_file "${RESOURCES_ROOT}/desktop/setup-assets/linux/install-goose.sh" 'bun
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/linux/install-junie.sh" 'bundled Linux Junie installer helper'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/linux/install-kiro-cli.sh" 'bundled Linux Kiro installer helper'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/linux/check-installation.sh" 'bundled Linux readiness audit helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/linux/provider-version-common.sh" 'bundled native version library'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/linux/verified-npm-update.sh" 'bundled npm verification library'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/linux/provider-cli-common.sh" 'bundled Linux provider helper library'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/linux/node-cli-common.sh" 'bundled Linux npm helper library'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/manifest.json" 'bundled setup-assets manifest'

package/scripts/linux/verified-npm-update.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Usage: source verified-npm-update.sh; cats_upgrade_npm
+# Explicit npm upgrade only. Adapted from environment-bootstrap 4690075.
+# Preserve the current prefix (including nvm), enforce engines, verify command and package.
+cats_upgrade_npm() {
+  local current latest installed root
+  current="$(npm --version)" || { printf 'Could not read npm version.\n' >&2; return 1; }
+  latest="$(npm view npm@latest version --fetch-retries=0 --fetch-timeout=10000 --loglevel=error)" || { printf 'npm version query failed.\n' >&2; return 1; }
+  [[ "$latest" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { printf 'Invalid npm version metadata.\n' >&2; return 1; }
+  [ "$current" != "$latest" ] || return 0
+  [ "$(cats_version_compare "$current" "$latest")" != 1 ] || return 0
+  npm install -g "npm@$latest" --engine-strict --fetch-retries=0 --fetch-timeout=30000 || return 1
+  hash -r
+  installed="$(npm --version)" && root="$(npm root -g)" || return 1
+  [ "$installed" = "$latest" ] && node -e '
+    const path = require("path");
+    const pkg = require(path.join(process.argv[1], "npm", "package.json"));
+    process.exit(pkg.version === process.argv[2] ? 0 : 1);
+  ' "$root" "$latest" || { printf 'npm verification failed. Check PATH and prefix.\n' >&2; return 1; }
+}

package/scripts/macos/install-github-cli.sh

@@ -60,6 +60,11 @@ declare -a applied_changes=()
 declare -a warnings=()
 declare -a manual_steps=()
 
+# A Desktop-launched helper may inherit PATH from before gh was installed.
+# Include our fallback destination and the supported Homebrew locations in this
+# process only; check mode must not edit the user's shell profile.
+export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
+
 resolve_gh_path() {
   command -v gh 2>/dev/null || true
 }

package/scripts/macos/install-node.sh

@@ -90,7 +90,7 @@ is_node_installed() {
   if [ "$skip_node_probe" = 'true' ]; then
     return 1
   fi
-  command -v node >/dev/null 2>&1
+  command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1
 }
 
 json_array_from_lines() {
@@ -149,6 +149,12 @@ JSON
   exit "$exit_code"
 }
 
+# Desktop's environment may predate nvm installation. Load it before read-only
+# detection too; a bundled or standalone node without npm is not this substrate.
+if [ "$install_state" = 'auto' ] && [ "$skip_node_probe" = 'false' ]; then
+  load_nvm
+fi
+
 # Mode: check
 if [ "$mode" = 'check' ]; then
   if is_node_installed; then
@@ -214,10 +220,10 @@ case "$mode" in
     ;;
 esac
 
-if command -v node >/dev/null 2>&1; then
+if command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1; then
   emit_result 'ready' 'true' 0
 else
-  warnings+=('Node binary still missing after install.')
+  warnings+=('Node.js or npm is still missing after install.')
   manual_steps+=('Open a new terminal so PATH picks up the nvm-managed node binary.')
   emit_result 'failed' 'false' 1
 fi