feat: add --release flag to playground for pre-built binaries (#19)

* feat: add --release flag to playground for pre-built binaries

The playground script can now download pre-built binaries from GitHub
Releases instead of building from source, making it faster to try
Reaper without any build toolchain. Defaults to latest release when
no version is specified.

Also clarifies in the README that no Rust toolchain is needed for the
playground (builds happen inside Docker or are skipped entirely with
--release).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* test: add integration tests for --release resolution modes

Extract resolve_latest_release() into scripts/lib/release-utils.sh so
it can be sourced independently. Add test-playground-release.sh with 9
tests covering:

- Latest release resolution via gh CLI (authenticated)
- Latest release resolution via curl (unauthenticated GitHub API)
- Consistency check between both methods
- curl works without GITHUB_TOKEN credentials
- Argument parsing: --release (bare), --release v0.2.4, --release --flag
- --help output includes --release documentation
- Graceful failure for nonexistent repos

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* ci: add playground release tests to CI pipeline

Add a lightweight job to the Tests workflow that runs the --release
resolution tests in parallel with existing jobs. No Rust, Docker, or
Kind needed — just checkout and run.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: miguelgila

.github/workflows/test.yml

@@ -157,3 +157,12 @@ jobs:
 
       - name: Check formatting
         run: cargo fmt -- --check
+
+  playground-release:
+    name: Playground Release Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Test --release resolution modes
+        run: ./scripts/test-playground-release.sh

README.md

@@ -39,15 +39,23 @@ Reaper is a containerd shim that runs processes directly on the host system whil
 
 ### Playground (try it locally)
 
-Spin up a 3-node Kind cluster with Reaper pre-installed:
+Spin up a 3-node Kind cluster with Reaper pre-installed. No Rust toolchain needed.
+
+**Quickest way** — download pre-built binaries from the latest [GitHub Release](https://github.com/miguelgila/reaper/releases):
 
 ```bash
 # Prerequisites: Docker, kind, kubectl, ansible (pip install ansible)
+./scripts/setup-playground.sh --release
+```
+
+**Build from source** — compiles inside Docker (still no local Rust needed):
+
+```bash
 ./scripts/setup-playground.sh
 ```
 
-This builds Reaper, creates a Kind cluster with 1 control-plane + 2 worker nodes,
-installs the runtime on all nodes, and runs a smoke test. Once ready, try:
+Both create a Kind cluster with 1 control-plane + 2 worker nodes, install the
+runtime on all nodes, and run a smoke test. Once ready, try:
 
 ```bash
 kubectl run hello --rm -it --image=busybox --restart=Never \
@@ -267,12 +275,15 @@ The [examples/](examples/) directory contains runnable demos, each with a `setup
 - **Kubernetes cluster** with containerd runtime
 - **Root access** on cluster nodes (required for containerd shim installation)
 
-**Local development / playground:**
+**Playground (no Rust needed):**
 - [Docker](https://docs.docker.com/get-docker/)
 - [kind](https://kind.sigs.k8s.io/) (Kubernetes in Docker)
 - [kubectl](https://kubernetes.io/docs/tasks/tools/)
 - [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/) (`pip install ansible`)
 
+**Local development (building from source natively):**
+- All of the above, plus [Rust](https://www.rust-lang.org/tools/install) (toolchain version pinned in `rust-toolchain.toml`)
+
 **Note:** Overlay filesystem is Linux-only. On macOS, the runtime compiles but overlay features are disabled.
 
 ## Testing

scripts/lib/release-utils.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# release-utils.sh — GitHub release resolution helpers.
+# Sourced by setup-playground.sh and test scripts; do not execute directly.
+
+GITHUB_REPO="${GITHUB_REPO:-miguelgila/reaper}"
+
+# resolve_latest_release — Print the tag name of the latest GitHub release.
+#
+# Tries `gh` CLI first (handles auth and rate limits), then falls back to
+# the unauthenticated GitHub REST API via `curl` (60 requests/hour per IP).
+#
+# Outputs the tag (e.g., "v0.2.4") on stdout.
+# Returns non-zero and prints an error on stderr if resolution fails.
+resolve_latest_release() {
+  local latest=""
+
+  # Path 1: gh CLI (if available)
+  if command -v gh >/dev/null 2>&1; then
+    latest=$(gh release view --repo "$GITHUB_REPO" --json tagName -q '.tagName' 2>/dev/null) || true
+  fi
+
+  # Path 2: curl fallback (unauthenticated GitHub API)
+  if [[ -z "${latest:-}" ]]; then
+    latest=$(curl -fsSL "https://api.github.com/repos/${GITHUB_REPO}/releases/latest" 2>/dev/null \
+      | grep '"tag_name"' | head -1 | sed 's/.*"tag_name": *"\([^"]*\)".*/\1/') || true
+  fi
+
+  if [[ -z "${latest:-}" ]]; then
+    echo "ERROR: Could not determine latest release for $GITHUB_REPO" >&2
+    return 1
+  fi
+
+  echo "$latest"
+}

scripts/setup-playground.sh

@@ -2,7 +2,9 @@
 # setup-playground.sh — Create a Reaper-enabled Kind cluster for manual testing.
 #
 # Usage:
-#   ./scripts/setup-playground.sh                          # Create 3-node playground
+#   ./scripts/setup-playground.sh                          # Build from source + create cluster
+#   ./scripts/setup-playground.sh --release                # Use latest GitHub release (no build)
+#   ./scripts/setup-playground.sh --release v0.2.4         # Use specific GitHub release
 #   ./scripts/setup-playground.sh --cleanup                # Delete playground cluster
 #   ./scripts/setup-playground.sh --cluster-name my-test   # Custom cluster name
 #   ./scripts/setup-playground.sh --kind-config <path>     # Custom Kind config
@@ -13,6 +15,7 @@
 #   - kind (https://kind.sigs.k8s.io/)
 #   - kubectl
 #   - ansible-playbook (pip install ansible)
+#   - curl (for --release mode)
 #   - Run from the repository root
 
 set -euo pipefail
@@ -25,6 +28,7 @@ KIND_CONFIG=""          # empty = generate default 3-node config
 SKIP_BUILD=false
 QUIET=false
 CLEANUP=false
+RELEASE_VERSION=""      # empty = build from source; "latest" or "vX.Y.Z" = download
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
@@ -86,6 +90,16 @@ while [[ $# -gt 0 ]]; do
       [[ ! -f "$KIND_CONFIG" ]] && fail "Kind config not found: $KIND_CONFIG"
       shift 2
       ;;
+    --release)
+      # Accept optional version argument; default to "latest"
+      if [[ -n "${2:-}" ]] && [[ "$2" != --* ]]; then
+        RELEASE_VERSION="$2"
+        shift 2
+      else
+        RELEASE_VERSION="latest"
+        shift
+      fi
+      ;;
     --skip-build)
       SKIP_BUILD=true
       shift
@@ -100,10 +114,11 @@ while [[ $# -gt 0 ]]; do
       echo "Create a Reaper-enabled Kind cluster for testing."
       echo ""
       echo "Options:"
+      echo "  --release [version]     Use pre-built binaries from GitHub Releases (default: latest)"
       echo "  --cleanup               Delete the playground cluster"
       echo "  --cluster-name <name>   Cluster name (default: reaper-playground)"
       echo "  --kind-config <path>    Custom Kind config file (default: 3-node cluster)"
-      echo "  --skip-build            Skip binary cross-compilation"
+      echo "  --skip-build            Skip binary cross-compilation (when building from source)"
       echo "  --quiet                 Suppress output (for scripted use)"
       echo "  -h, --help              Show this help"
       echo ""
@@ -198,12 +213,32 @@ else
 fi
 
 # ---------------------------------------------------------------------------
-# Build static musl binaries
+# Resolve "latest" release version
 # ---------------------------------------------------------------------------
-if ! $SKIP_BUILD; then
-  info "Building Reaper binaries for Kind nodes" | if_log
+# shellcheck source=lib/release-utils.sh
+source "$SCRIPT_DIR/lib/release-utils.sh"
+
+if [[ -n "$RELEASE_VERSION" ]]; then
+  if [[ "$RELEASE_VERSION" == "latest" ]]; then
+    info "Resolving latest release..." | if_log
+    RELEASE_VERSION=$(resolve_latest_release) || \
+      fail "Could not determine latest release. Check https://github.com/${GITHUB_REPO}/releases or specify a version: --release v0.2.4"
+    ok "Latest release: $RELEASE_VERSION" | if_log
+  fi
+fi
 
-  cd "$REPO_ROOT"
+# ---------------------------------------------------------------------------
+# Obtain binaries (release download OR build from source)
+# ---------------------------------------------------------------------------
+cd "$REPO_ROOT"
+
+if [[ -n "$RELEASE_VERSION" ]]; then
+  # --release mode: delegate to install-reaper.sh which handles download
+  info "Using pre-built release $RELEASE_VERSION (skipping build)" | if_log
+  INSTALL_RELEASE_ARGS="--release $RELEASE_VERSION"
+
+elif ! $SKIP_BUILD; then
+  info "Building Reaper binaries for Kind nodes" | if_log
 
   NODE_ID=$(docker ps --filter "name=${CLUSTER_NAME}-control-plane" --format '{{.ID}}')
   NODE_ARCH=$(docker exec "$NODE_ID" uname -m 2>&1) || fail "Cannot detect node architecture"
@@ -259,22 +294,24 @@ if ! $SKIP_BUILD; then
   fi
 
   ok "Binaries built." | if_log
+  INSTALL_RELEASE_ARGS=""
 else
   info "Skipping build (--skip-build)" | if_log
-  cd "$REPO_ROOT"
+  INSTALL_RELEASE_ARGS=""
 fi
 
 # ---------------------------------------------------------------------------
 # Install Reaper on all nodes via Ansible
 # ---------------------------------------------------------------------------
 info "Installing Reaper runtime on all nodes" | if_log
 
+# shellcheck disable=SC2086
 if $QUIET; then
-  ./scripts/install-reaper.sh --kind "$CLUSTER_NAME" >> "$LOG_FILE" 2>&1 || {
+  ./scripts/install-reaper.sh --kind "$CLUSTER_NAME" $INSTALL_RELEASE_ARGS >> "$LOG_FILE" 2>&1 || {
     fail "Ansible install failed. See $LOG_FILE for details."
   }
 else
-  ./scripts/install-reaper.sh --kind "$CLUSTER_NAME" 2>&1 | tee -a "$LOG_FILE" || {
+  ./scripts/install-reaper.sh --kind "$CLUSTER_NAME" $INSTALL_RELEASE_ARGS 2>&1 | tee -a "$LOG_FILE" || {
     fail "Ansible install failed. See $LOG_FILE for details."
   }
 fi