fix(install): honor pinned releases and speed up prerelease discovery (#3681)

* fix(install): use native packages for prereleases and speed up discovery

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

* fix(install): honor pinned versions and guard Snap migration

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

* fix(install): omit Snap migration guard

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

---------

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

Author: drew

README.md

@@ -300,7 +300,8 @@ curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh |
   OPENSHELL_VERSION=pre sh
 ```
 
-The installer downloads only the artifact for the current platform and rejects expired candidates during discovery. Installed packages retain the candidate's exact version, such as `0.1.0-pre.3`. Prerelease tags do not create entries on the GitHub Releases page.
+The installer checks prerelease tags from newest to oldest, selects an unexpired artifact from a successful release run for the current platform, and downloads only that artifact. Installed packages retain the candidate's exact version, such as `0.1.0-pre.3`. Prerelease tags do not create entries on the GitHub Releases page.
+On Linux, prereleases and explicit release tags use Debian or RPM packages even if `snap` is installed.
 
 The rolling [`dev` release](https://github.com/NVIDIA/OpenShell/releases/tag/dev) does not require GitHub authentication:
 

architecture/build.md

@@ -324,6 +324,12 @@ positive canary uses system Docker; negative preflight coverage verifies that
 the installer rejects both missing Docker and the Docker Snap before installing
 OpenShell. Its Debian lane removes snapd before running the installer so Snap
 precedence cannot change the package under test.
+Explicit release tags and the `pre` alias bypass Snap selection and use the
+native Debian or RPM package path even when `snap` is available. The `pre` alias
+checks matching Git tags in version order, then looks up the exact platform
+artifact and verifies the release run instead of listing every repository
+artifact.
+
 Snapd runs the gateway as a root-owned system service. Its generated client
 certificates reside in root-owned snap state and are unavailable to ordinary CLI
 users, so the Snap uses plaintext loopback transport and enables unauthenticated

docs/about/installation.mdx

@@ -19,11 +19,11 @@ Install OpenShell with a single command:
 curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
 ```
 
-The script detects your operating system and installs the OpenShell CLI, standalone policy prover, and gateway. On Linux, it installs from the Snap Store whenever the `snap` command is available. Otherwise, it uses the native Debian or RPM package. It then starts the local gateway server so you can begin creating sandboxes.
+The script detects your operating system and installs the OpenShell CLI, standalone policy prover, and gateway. On Linux, it installs from the Snap Store when `snap` is available and `OPENSHELL_VERSION` is unset or `dev`. Explicit release tags and prereleases use the native Debian or RPM package. It then starts the local gateway server so you can begin creating sandboxes.
 
 Snap installs use `latest/stable` by default and `latest/edge` when
-`OPENSHELL_VERSION=dev`. Other `OPENSHELL_VERSION` values also use the stable
-Snap channel because Snap Store channels do not select an exact GitHub release.
+`OPENSHELL_VERSION=dev`. Set `OPENSHELL_VERSION` to a release tag to install
+that exact Debian or RPM version, even if `snap` is available.
 
 You can also download release artifacts directly from the [OpenShell GitHub Releases](https://github.com/NVIDIA/OpenShell/releases) page.
 
@@ -75,13 +75,15 @@ brew services restart openshell
 ## Linux
 
 On Linux systems with the `snap` command, the install script uses the OpenShell
-snap. Install and start Docker Engine from a system package or Docker's package
-repository before running the installer. The Docker snap is not currently
-compatible with OpenShell.
+snap when `OPENSHELL_VERSION` is unset or `dev`. Explicit release tags and the
+`pre` prerelease alias use Debian or RPM packages even when `snap` is available.
+For Snap installs, install and start Docker Engine from a system package or
+Docker's package repository first. The Docker snap is not currently compatible
+with OpenShell.
 
-On Fedora and RHEL without `snap`, the install script uses RPM packages. The RPMs install the `openshell` CLI, `openshell-prover`, the `openshell-gateway` daemon, and a systemd user service.
+On Fedora and RHEL without `snap`, or when a release tag or `pre` is specified, the install script uses RPM packages. The RPMs install the `openshell` CLI, `openshell-prover`, the `openshell-gateway` daemon, and a systemd user service.
 
-On Debian and Ubuntu without `snap`, the install script uses a Debian package. The Debian package installs the `openshell` CLI, `openshell-prover`, the `openshell-gateway` daemon, VM sandbox support, and a systemd user service.
+On Debian and Ubuntu without `snap`, or when a release tag or `pre` is specified, the install script uses a Debian package. The Debian package installs the `openshell` CLI, `openshell-prover`, the `openshell-gateway` daemon, VM sandbox support, and a systemd user service.
 
 Linux packages require glibc 2.28 or newer. The installer checks libc before downloading packages and exits with an error on older glibc versions, Alpine, musl-based distributions, or unknown libc environments.
 

install.sh

@@ -66,14 +66,16 @@ NOTES:
     When OPENSHELL_VERSION is unset, this resolves the latest tagged release
     from ${GITHUB_URL}/releases/latest.
 
-    On Linux, the installer uses the OpenShell snap whenever the snap command
-    is available. It installs from latest/edge when OPENSHELL_VERSION=dev and
-    from latest/stable otherwise. The OpenShell snap requires a running Docker
-    Engine installed from a system package or Docker's package repository. The
-    Docker snap is not currently compatible with OpenShell.
-
-    Without snap, Linux installs the Debian package on amd64/arm64 or the RPM
-    packages on x86_64/aarch64, depending on the host package manager.
+    On Linux, the installer uses the OpenShell snap when the snap command is
+    available and OPENSHELL_VERSION is unset or dev. Snap installs use
+    latest/stable by default and latest/edge for dev. Explicit release tags
+    and prereleases use Debian or RPM packages. The OpenShell snap requires a
+    running Docker Engine installed from a system package or Docker's package
+    repository. The Docker snap is not currently compatible with OpenShell.
+
+    For explicit versions or without snap, Linux installs the Debian package
+    on amd64/arm64 or the RPM packages on x86_64/aarch64, depending on the
+    host package manager.
     macOS installs the release Homebrew formula on Apple Silicon and starts a
     brew services-backed local gateway.
 EOF
@@ -432,61 +434,39 @@ resolve_latest_prerelease_tag() {
 
   info "resolving latest prerelease..."
   _artifact_platform="$(prerelease_artifact_platform)"
-  _successful_run_ids="$(gh api --paginate \
-    "repos/${REPO}/actions/workflows/release-tag.yml/runs?status=success&per_page=100" \
-    --jq '.workflow_runs[] | select(.status == "completed" and .conclusion == "success") | .id')" || {
-    error "failed to list successful Release Tag workflow runs"
+  _release_tags="$(gh api "repos/${REPO}/git/matching-refs/tags/v" --jq '
+    [.[].ref | sub("^refs/tags/"; "") |
+      select(test("^v[0-9]+\\.[0-9]+\\.[0-9]+-pre\\.[1-9][0-9]*$"))] |
+    sort_by(split("-pre.") as $parts |
+      ($parts[0] | ltrimstr("v") | split(".") | map(tonumber)) +
+      [($parts[1] | tonumber)]) | reverse | .[]')" || {
+    error "failed to list prerelease tags"
   }
-  _artifact_records="$(gh api --paginate \
-    "repos/${REPO}/actions/artifacts?per_page=100" \
-    --jq '.artifacts[] | select(.expired == false) | [.workflow_run.id, .name] | @tsv')" || {
-    error "failed to list prerelease artifacts"
-  }
-  _artifact_names="$(printf '%s\n--ARTIFACTS--\n%s\n' "$_successful_run_ids" "$_artifact_records" | awk -F '\t' '
-    $0 == "--ARTIFACTS--" {
-      reading_artifacts = 1
-      next
-    }
-    !reading_artifacts {
-      if ($1 ~ /^[0-9]+$/) successful_runs[$1] = 1
-      next
-    }
-    $1 in successful_runs {
-      print $2
-    }
-  ')"
-  _release_tags="$(printf '%s\n' "$_artifact_names" | sed -n "s/^openshell-\(v[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*-pre\.[1-9][0-9]*\)-${_artifact_platform}$/\1/p" | sort -u)"
-
-  _latest_prerelease="$(printf '%s\n' "$_release_tags" | awk '
-    /^v[0-9]+\.[0-9]+\.[0-9]+-pre\.[1-9][0-9]*$/ {
-      tag = $0
-      sub(/^v/, "", tag)
-      split(tag, version_parts, "-pre[.]")
-      split(version_parts[1], core, "[.]")
-      sequence = version_parts[2] + 0
-
-      if (!found || core[1] + 0 > major ||
-          (core[1] + 0 == major && core[2] + 0 > minor) ||
-          (core[1] + 0 == major && core[2] + 0 == minor && core[3] + 0 > patch) ||
-          (core[1] + 0 == major && core[2] + 0 == minor && core[3] + 0 == patch && sequence > prerelease)) {
-        selected = $0
-        major = core[1] + 0
-        minor = core[2] + 0
-        patch = core[3] + 0
-        prerelease = sequence
-        found = 1
-      }
-    }
-    END {
-      if (found) print selected
+
+  for _tag in $_release_tags; do
+    _artifact_name="openshell-${_tag}-${_artifact_platform}"
+    info "checking ${_tag} for ${_artifact_platform}..."
+    _run_ids="$(gh api \
+      "repos/${REPO}/actions/artifacts?name=${_artifact_name}&per_page=100" \
+      --jq '[.artifacts[] | select(.expired == false)] |
+        sort_by(.created_at) | reverse | .[] | .workflow_run.id')" || {
+      error "failed to find prerelease artifact ${_artifact_name}"
     }
-  ')"
 
-  if [ -z "$_latest_prerelease" ]; then
-    error "no unexpired prerelease artifacts found"
-  fi
+    for _run_id in $_run_ids; do
+      _successful="$(gh api "repos/${REPO}/actions/runs/${_run_id}" --jq '
+        .status == "completed" and .conclusion == "success" and
+        (.path | startswith(".github/workflows/release-tag.yml"))')" || {
+        error "failed to check prerelease workflow run ${_run_id}"
+      }
+      if [ "$_successful" = "true" ]; then
+        printf '%s\n' "$_tag"
+        return 0
+      fi
+    done
+  done
 
-  printf '%s\n' "$_latest_prerelease"
+  error "no unexpired prerelease artifacts found"
 }
 
 is_prerelease_tag() {
@@ -678,9 +658,16 @@ local_gateway_endpoint() {
 }
 
 linux_package_method() {
-  if has_cmd snap; then
-    echo "snap"
-  elif has_cmd dpkg; then
+  case "${OPENSHELL_VERSION:-}" in
+    '' | dev)
+      if has_cmd snap; then
+        echo "snap"
+        return 0
+      fi
+      ;;
+  esac
+
+  if has_cmd dpkg; then
     echo "deb"
   elif has_cmd rpm; then
     echo "rpm"
@@ -1226,14 +1213,11 @@ install_linux_rpm() {
 }
 
 openshell_snap_channel() {
-  if [ "${OPENSHELL_VERSION:-}" = "dev" ]; then
-    printf '%s\n' "latest/edge"
-  else
-    if [ -n "${OPENSHELL_VERSION:-}" ]; then
-      warn "OPENSHELL_VERSION=${OPENSHELL_VERSION} is ignored for Snap installs; using latest/stable"
-    fi
-    printf '%s\n' "latest/stable"
-  fi
+  case "${OPENSHELL_VERSION:-}" in
+    dev) printf '%s\n' "latest/edge" ;;
+    '') printf '%s\n' "latest/stable" ;;
+    *) error "Snap installs do not support OPENSHELL_VERSION=${OPENSHELL_VERSION}; use a native package" ;;
+  esac
 }
 
 ensure_snap_gateway_config() {

tasks/scripts/test-install-sh.sh

@@ -102,13 +102,15 @@ assert_glibc_preflight_fails \
 
 assert_linux_package_method() {
   local name=$1
-  local snap_present=$2
-  local dpkg_present=$3
-  local rpm_present=$4
-  local expected=$5
+  local requested_version=$2
+  local snap_present=$3
+  local dpkg_present=$4
+  local rpm_present=$5
+  local expected=$6
   local actual
 
   actual="$(
+    export OPENSHELL_VERSION="$requested_version"
     has_cmd() {
       case "$1" in
         snap) [ "$snap_present" = "1" ] ;;
@@ -125,9 +127,16 @@ assert_linux_package_method() {
   fi
 }
 
-assert_linux_package_method "snap takes precedence over deb and rpm" 1 1 1 snap
-assert_linux_package_method "deb is selected without snap" 0 1 1 deb
-assert_linux_package_method "rpm is selected without snap or deb" 0 0 1 rpm
+assert_linux_package_method "snap takes precedence over deb and rpm" "" 1 1 1 snap
+assert_linux_package_method "dev uses snap" dev 1 1 1 snap
+assert_linux_package_method "pre uses deb despite snap" pre 1 1 1 deb
+assert_linux_package_method "numbered prerelease uses deb despite snap" v0.1.0-pre.3 1 1 1 deb
+assert_linux_package_method "pre uses rpm despite snap" pre 1 0 1 rpm
+assert_linux_package_method "pinned stable uses deb despite snap" v1.2.3 1 1 1 deb
+assert_linux_package_method "pinned stable uses rpm despite snap" v1.2.3 1 0 1 rpm
+assert_linux_package_method "deb is selected without snap" "" 0 1 1 deb
+assert_linux_package_method "dev uses deb without snap" dev 0 1 1 deb
+assert_linux_package_method "rpm is selected without snap or deb" "" 0 0 1 rpm
 
 if ! (
   find_existing_native_openshell_bin() { return 1; }
@@ -223,22 +232,15 @@ if [ -s "$err" ]; then
   exit 1
 fi
 
-for requested_version in pre v1.2.3; do
-  if ! OPENSHELL_VERSION="$requested_version" openshell_snap_channel >"$out" 2>"$err"; then
-    echo "FAIL: '${requested_version}' must select the latest/stable Snap channel" >&2
-    cat "$err" >&2 || true
-    exit 1
-  fi
-  if [ "$(cat "$out")" != "latest/stable" ]; then
-    echo "FAIL: '${requested_version}' must select the latest/stable Snap channel" >&2
-    exit 1
-  fi
-  if ! grep -Fq "OPENSHELL_VERSION=${requested_version} is ignored for Snap installs" "$err"; then
-    echo "FAIL: '${requested_version}' must warn that the requested version is ignored" >&2
-    cat "$err" >&2 || true
-    exit 1
-  fi
-done
+if (OPENSHELL_VERSION=v1.2.3 openshell_snap_channel) >"$out" 2>"$err"; then
+  echo "FAIL: pinned release must not select a Snap channel" >&2
+  exit 1
+fi
+if ! grep -Fq "Snap installs do not support OPENSHELL_VERSION=v1.2.3" "$err"; then
+  echo "FAIL: pinned release Snap rejection was not explained" >&2
+  cat "$err" >&2
+  exit 1
+fi
 rm -f "$out" "$err"
 
 assert_snap_install_flow() {
@@ -299,7 +301,7 @@ wait:gateway-status"
 
 assert_snap_install_flow \
   "existing OpenShell snap is refreshed" \
-  1 1 pre \
+  1 1 "" \
   "wait:docker
 root:snap refresh openshell --channel=latest/stable
 ensure:gateway-config
@@ -502,19 +504,21 @@ gh() {
       ;;
     api:*)
       case "$*" in
-        *"?name="*) printf '123456\n' ;;
-        *"actions/workflows/release-tag.yml/runs?status=success"*)
-          printf '%s\n' 100 101
+        *"git/matching-refs/tags/v"*)
+          printf '%s\n' v2.0.0-pre.1 v1.0.0-pre.2 v0.1.0-pre.9
+          ;;
+        *"?name=openshell-v2.0.0-pre.1-linux-amd64-deb"*)
+          [ "${MOCK_NO_PRERELEASE:-0}" = "1" ] || printf '999\n'
+          ;;
+        *"?name=openshell-v1.0.0-pre.2-linux-amd64-deb"*)
+          [ "${MOCK_NO_PRERELEASE:-0}" = "1" ] || printf '101\n'
           ;;
+        *"?name=openshell-v0.1.0-pre.9-linux-amd64-deb"*)
+          [ "${MOCK_NO_PRERELEASE:-0}" = "1" ] || printf '123456\n'
+          ;;
+        *"actions/runs/999"*) printf 'false\n' ;;
+        *"actions/runs/101"*) printf 'true\n' ;;
         *)
-          if [ "${MOCK_NO_PRERELEASE:-0}" != "1" ]; then
-            printf '%b\n' \
-              '100\topenshell-v0.1.0-pre.9-linux-amd64-deb' \
-              '101\topenshell-v1.0.0-pre.2-linux-amd64-deb' \
-              '101\topenshell-v1.0.0-pre.1-macos-arm64' \
-              '101\topenshell-v0.2.0-pre.10-linux-aarch64-rpm' \
-              '999\topenshell-v2.0.0-pre.1-linux-amd64-deb'
-          fi
           ;;
       esac
       ;;
@@ -539,13 +543,29 @@ if [ "$resolved_prerelease" != "v1.0.0-pre.2" ]; then
   echo "FAIL: pre alias resolved to ${resolved_prerelease}, expected v1.0.0-pre.2" >&2
   exit 1
 fi
-if ! grep -Fq 'actions/workflows/release-tag.yml/runs?status=success' "$mock_gh_log"; then
-  echo "FAIL: pre alias did not query successful Release Tag workflow runs" >&2
+if ! grep -Fq 'git/matching-refs/tags/v' "$mock_gh_log"; then
+  echo "FAIL: pre alias did not query prerelease tags" >&2
+  cat "$mock_gh_log" >&2
+  exit 1
+fi
+if ! grep -Fq 'actions/artifacts?name=openshell-v1.0.0-pre.2-linux-amd64-deb' "$mock_gh_log"; then
+  echo "FAIL: pre alias did not query the platform artifact by name" >&2
+  cat "$mock_gh_log" >&2
+  exit 1
+fi
+if ! grep -Fq 'actions/runs/999' "$mock_gh_log" ||
+  ! grep -Fq 'actions/runs/101' "$mock_gh_log"; then
+  echo "FAIL: pre alias did not skip an unsuccessful run" >&2
+  cat "$mock_gh_log" >&2
+  exit 1
+fi
+if ! grep -Fq '.conclusion == "success"' "$mock_gh_log"; then
+  echo "FAIL: pre alias did not require a successful workflow run" >&2
   cat "$mock_gh_log" >&2
   exit 1
 fi
-if ! grep -Fq 'select(.status == "completed" and .conclusion == "success")' "$mock_gh_log"; then
-  echo "FAIL: pre alias did not require completed successful workflow runs" >&2
+if grep -Fq -- '--paginate' "$mock_gh_log"; then
+  echo "FAIL: pre alias must not scan every workflow run or artifact" >&2
   cat "$mock_gh_log" >&2
   exit 1
 fi