fix(install): unbreak macOS, atomic Linux install, real version smoke test

staylor · staylor · commit 400500efe9df · 2026-05-05T10:30:14.000-04:00
The current install script has three issues that affect every user:

1. macOS install produces a binary the kernel kills at exec
   The nightly Mach-O assets from GitHub Releases (lightpanda-aarch64-macos,
   lightpanda-x86_64-macos) get SIGKILLed at exec on Apple Silicon despite
   shipping with an ad-hoc / linker signature. Ad-hoc re-signing locally
   does not help. Reproduces 100% of the time on M-series Macs running the
   release asset directly. The existing brew tap at
   lightpanda-io/browser/lightpanda builds from source and produces a binary
   that runs, so route Darwin through it.

2. Linux install destroys an existing working binary on any failed rerun
   SKILL.md documents reruns of this script as the update path:

     &gt; If you encounter crashes or issues, run scripts/install.sh again to
     &gt; update to the latest version (max once per day).

   But `curl -L -o "$INSTALL_DIR/$BINARY_NAME"` overwrites the install
   target during download. A failed download (network drop, checksum
   mismatch, unrunnable replacement) leaves the user with no binary or a
   broken one even though they had a working one before. Atomic install via
   mktemp -&gt; verify -&gt; smoke-test -&gt; mv preserves the existing binary on
   any failure.

3. Smoke test silently accepts broken binaries
   The test currently is:

     "$INSTALL_DIR/$BINARY_NAME" --version 2&gt;/dev/null || \
       "$INSTALL_DIR/$BINARY_NAME" --help 2&gt;/dev/null | head -1

   Lightpanda's CLI does not have a --version flag. Running it logs
   '$msg=exit err=UnknownCommand' to stderr and exits 1. The 2&gt;/dev/null
   masks this and the script falls through to the --help branch. On a
   binary that crashes at exec (the macOS case above), --help also fails,
   but the surrounding 'if ... | head -1; then' construction still ends in
   the success branch on macOS because head exits 0 on empty stdin.
   Result: 'Lightpanda installed successfully!' for an unrunnable binary.

   Use the 'version' subcommand (which is the actual Lightpanda CLI form),
   capture stderr to a tempfile, and fail hard with the binary's stderr
   surfaced so users see real diagnostics like 'GLIBC_2.32 not found' on
   incompatible systems.

## Other changes in this PR

- `set -euo pipefail` (was `set -e`). `pipefail` propagates a failing
  curl through `curl | jq` (jq exits 0 on empty input, otherwise hiding
  network errors behind a misleading 'could not retrieve checksum').
- `chmod 0755` instead of `chmod a+x`. mktemp creates 0600; `a+x` on
  top of that is 0711 (owner-only readable), which is surprising on a
  shared install path.
- Optional $GITHUB_TOKEN raises the GitHub API quota from 60-&gt;5000/hr.
  Branched curl call rather than building a header array — Bash &lt;=4.3
  (RHEL 7, old containers) errors on empty-array expansion under `set -u`.
- PATH-shadow check on both macOS and Linux. Warns when another
  `lightpanda` is earlier in PATH than the freshly installed one
  (catches stale binaries from earlier install attempts).
- SKILL.md install section gains a per-OS strategy callout describing
  the new flow.

## Verified

End-to-end run on Apple Silicon (after first reverting the broken release
binary): brew install/upgrade succeeds, version subcommand prints
'1.0.0-nightly.6051+d360fcc0', PATH check passes.
diff --git a/SKILL.md b/SKILL.md
@@ -25,7 +25,9 @@ Prefer the built-in Web Search tool when it is available and sufficient for your
 bash scripts/install.sh
 ```
 
-Lightpanda is available on Linux and macOS only. Windows is supported via WSL2.
+Lightpanda is available on Linux and macOS only. Windows is supported via WSL2. The script picks the right method per OS:
+- **macOS** — installs via the upstream Homebrew tap (`brew install lightpanda-io/browser/lightpanda`). Requires Homebrew. The nightly Mach-O binaries from GitHub Releases get killed by the kernel on Apple Silicon despite shipping with an ad-hoc / linker signature, so the script delegates to the tap, which builds from source.
+- **Linux** — downloads the nightly binary from GitHub Releases, verifies its SHA-256, smoke-tests it, and atomically installs to `$HOME/.local/bin/lightpanda` (override with `LIGHTPANDA_DIR=...`). On rerun, the existing binary is left in place if any step fails.
 
 The binary is a nightly build that evolves quickly. If you encounter crashes or issues, run `scripts/install.sh` again to update to the latest version (max once per day).
 
diff --git a/scripts/install.sh b/scripts/install.sh
@@ -1,16 +1,24 @@
 #!/bin/bash
 # Lightpanda Setup Script
-# Run once to install Lightpanda browser
+# Run to install or update the Lightpanda browser binary.
+#
+# macOS  — installs via the upstream Homebrew tap. The nightly Mach-O
+#          assets from GitHub Releases are SIGKILLed at exec on Apple
+#          Silicon despite shipping with an ad-hoc / linker signature,
+#          so we delegate to brew which builds from source.
+# Linux  — downloads the nightly asset, verifies its SHA-256, smoke-
+#          tests it, and atomically `mv`s it into $LIGHTPANDA_DIR
+#          (default $HOME/.local/bin). The existing binary is left in
+#          place if any step fails — this is the documented update path.
+
+# `pipefail` propagates a failing curl in `curl | jq` (jq exits 0 on
+# empty input). `-u` turns variable typos into hard errors.
+set -euo pipefail
 
-set -e
-
-INSTALL_DIR="${LIGHTPANDA_DIR:-$HOME/.local/bin}"
 BINARY_NAME="lightpanda"
 
 echo "=== Lightpanda Setup ==="
-echo "Install directory: $INSTALL_DIR"
 
-# Detect OS and architecture
 OS="$(uname -s)"
 ARCH="$(uname -m)"
 
@@ -30,18 +38,59 @@ case "$OS" in
         esac
         ;;
     Darwin)
-        case "$ARCH" in
-            x86_64)
-                DOWNLOAD_URL="https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-macos"
-                ;;
-            arm64|aarch64)
-                DOWNLOAD_URL="https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos"
-                ;;
-            *)
-                echo "ERROR: Unsupported architecture: $ARCH"
-                exit 1
-                ;;
-        esac
+        if ! command -v brew &> /dev/null; then
+            echo "ERROR: macOS install requires Homebrew (https://brew.sh)."
+            echo "Install Homebrew, then re-run this script. Or install Lightpanda directly:"
+            echo "  brew install lightpanda-io/browser/lightpanda"
+            exit 1
+        fi
+        echo "Detected: $OS $ARCH — installing via Homebrew tap (lightpanda-io/browser/lightpanda)."
+        # `install` is idempotent on an up-to-date install but does not
+        # auto-upgrade an existing one; `upgrade` after keeps reruns
+        # current. Both exit 0 in the up-to-date case and non-zero on
+        # real errors — let `set -e` propagate genuine failures.
+        brew install lightpanda-io/browser/lightpanda
+        brew upgrade lightpanda-io/browser/lightpanda
+        # Anchor verification to the brew prefix (general, not keg-
+        # specific): a stale `~/.local/bin/lightpanda` from an older
+        # curl-on-macOS attempt could shadow the brew binary and make
+        # us report success for a broken one.
+        BREW_PREFIX="$(brew --prefix)"
+        BIN_PATH="$BREW_PREFIX/bin/$BINARY_NAME"
+        if [ ! -x "$BIN_PATH" ]; then
+            echo "ERROR: Homebrew install completed but $BIN_PATH is missing."
+            echo "Try: brew link --overwrite lightpanda"
+            exit 1
+        fi
+        # Hard-fail smoke test: brew can produce a binary that crashes
+        # at exec (formula regression, missing dep). Stderr to a file
+        # so we can show real diagnostics on failure.
+        DARWIN_SMOKE_STDERR=$(mktemp)
+        trap 'rm -f "$DARWIN_SMOKE_STDERR"' EXIT
+        if VERSION_OUT=$("$BIN_PATH" version 2>"$DARWIN_SMOKE_STDERR") && [ -n "$VERSION_OUT" ]; then
+            : # ok
+        else
+            echo "ERROR: Homebrew-installed lightpanda failed its version smoke test (\`$BIN_PATH version\` returned no output or non-zero exit)."
+            if [ -s "$DARWIN_SMOKE_STDERR" ]; then
+                echo "  Binary stderr:"
+                sed 's/^/    /' "$DARWIN_SMOKE_STDERR"
+            fi
+            echo "  Try: brew reinstall lightpanda-io/browser/lightpanda"
+            exit 1
+        fi
+        echo ""
+        echo "Lightpanda installed via Homebrew: $VERSION_OUT"
+        echo "Binary location: $BIN_PATH"
+        # Warn if something earlier in PATH shadows the brew binary.
+        PATH_RESOLVED="$(command -v lightpanda 2>/dev/null || true)"
+        if [ -n "$PATH_RESOLVED" ] && [ "$PATH_RESOLVED" != "$BIN_PATH" ]; then
+            echo ""
+            echo "WARNING: another 'lightpanda' is earlier in your PATH:"
+            echo "  $PATH_RESOLVED"
+            echo "Remove it or reorder PATH so $BREW_PREFIX/bin takes precedence."
+        fi
+        echo "Run with: lightpanda serve --host 127.0.0.1 --port 9222"
+        exit 0
         ;;
     *)
         echo "ERROR: Unsupported OS: $OS"
@@ -50,10 +99,12 @@ case "$OS" in
         ;;
 esac
 
+# --- Linux flow ---
+INSTALL_DIR="${LIGHTPANDA_DIR:-$HOME/.local/bin}"
 echo "Detected: $OS $ARCH"
+echo "Install directory: $INSTALL_DIR"
 echo "Download URL: $DOWNLOAD_URL"
 
-# Check for required tools
 if ! command -v curl &> /dev/null; then
     echo "ERROR: curl not found. Please install curl."
     exit 1
@@ -69,65 +120,101 @@ if ! command -v sha256sum &> /dev/null && ! command -v shasum &> /dev/null; then
     exit 1
 fi
 
-# Create install directory
 mkdir -p "$INSTALL_DIR"
 
-# Determine asset name from URL
 ASSET_NAME="${DOWNLOAD_URL##*/}"
 
-# Fetch expected SHA256 digest from GitHub release API
+# api.github.com unauthenticated quota is 60/hr/IP; collide on shared
+# NAT or in CI. $GITHUB_TOKEN raises it to 5000/hr. Branch the curl
+# call rather than building an array of header args — `"${arr[@]}"`
+# under `set -u` errors on Bash <=4.3 (RHEL 7, old containers).
+GITHUB_API_URL="https://api.github.com/repos/lightpanda-io/browser/releases/tags/nightly"
 echo "Fetching expected checksum from GitHub API..."
-EXPECTED_DIGEST=$(curl -sL "https://api.github.com/repos/lightpanda-io/browser/releases/tags/nightly" \
-    | jq -r --arg name "$ASSET_NAME" '.assets[] | select(.name == $name) | .digest')
+if [ -n "${GITHUB_TOKEN:-}" ]; then
+    EXPECTED_DIGEST=$(curl -fSL -H "Authorization: Bearer $GITHUB_TOKEN" "$GITHUB_API_URL" \
+        | jq -r --arg name "$ASSET_NAME" '.assets[] | select(.name == $name) | .digest')
+else
+    EXPECTED_DIGEST=$(curl -fSL "$GITHUB_API_URL" \
+        | jq -r --arg name "$ASSET_NAME" '.assets[] | select(.name == $name) | .digest')
+fi
 
 if [ -z "$EXPECTED_DIGEST" ] || [ "$EXPECTED_DIGEST" = "null" ]; then
     echo "ERROR: Could not retrieve checksum for $ASSET_NAME from GitHub API."
     exit 1
 fi
 
-# Strip the "sha256:" prefix
 EXPECTED_SHA256="${EXPECTED_DIGEST#sha256:}"
 echo "Expected SHA256: $EXPECTED_SHA256"
 
-# Download binary
-echo "Downloading Lightpanda..."
-curl -L -o "$INSTALL_DIR/$BINARY_NAME" "$DOWNLOAD_URL"
+# Download to a temp file in the same directory, verify, smoke-test,
+# THEN atomically `mv` into place. SKILL.md documents reruns as the
+# update path, so a failed download must not destroy a working binary.
+TMP_BINARY=$(mktemp "$INSTALL_DIR/.${BINARY_NAME}.XXXXXX")
+SMOKE_STDERR=$(mktemp)
+trap 'rm -f "$TMP_BINARY" "$SMOKE_STDERR"' EXIT
+
+echo "Downloading Lightpanda to $TMP_BINARY..."
+curl -fSL -o "$TMP_BINARY" "$DOWNLOAD_URL"
 
-# Verify checksum
 echo "Verifying checksum..."
 if command -v sha256sum &> /dev/null; then
-    ACTUAL_SHA256=$(sha256sum "$INSTALL_DIR/$BINARY_NAME" | awk '{print $1}')
+    ACTUAL_SHA256=$(sha256sum "$TMP_BINARY" | awk '{print $1}')
 else
-    ACTUAL_SHA256=$(shasum -a 256 "$INSTALL_DIR/$BINARY_NAME" | awk '{print $1}')
+    ACTUAL_SHA256=$(shasum -a 256 "$TMP_BINARY" | awk '{print $1}')
 fi
 
 if [ "$ACTUAL_SHA256" != "$EXPECTED_SHA256" ]; then
     echo "ERROR: Checksum verification FAILED!"
     echo "  Expected: $EXPECTED_SHA256"
     echo "  Actual:   $ACTUAL_SHA256"
-    rm -f "$INSTALL_DIR/$BINARY_NAME"
+    echo "  Existing binary (if any) at $INSTALL_DIR/$BINARY_NAME was NOT replaced."
     exit 1
 fi
 
 echo "Checksum verified OK."
-chmod a+x "$INSTALL_DIR/$BINARY_NAME"
+# 0755 (conventional executable mode) rather than `chmod a+x` over
+# mktemp's 0600, which would yield 0711 (owner-only readable).
+chmod 0755 "$TMP_BINARY"
+
+# Smoke-test BEFORE replacing. Use the `version` subcommand — Lightpanda's
+# `--version` flag exits 1 with `UnknownCommand`, so it would falsely
+# reject a working binary. Capturing stdout to a variable means the `if`
+# exit status is the binary's exit status (no pipe to mask it).
+echo "Smoke-testing the downloaded binary..."
+if ! VERSION_OUT=$("$TMP_BINARY" version 2>"$SMOKE_STDERR") || [ -z "$VERSION_OUT" ]; then
+    echo "ERROR: Downloaded binary failed to run (\`version\` subcommand returned no output or non-zero exit)."
+    echo "  This may indicate an incompatible system, missing libc, or a corrupted release asset."
+    if [ -s "$SMOKE_STDERR" ]; then
+        echo "  Binary stderr:"
+        sed 's/^/    /' "$SMOKE_STDERR"
+    fi
+    echo "  Existing binary (if any) at $INSTALL_DIR/$BINARY_NAME was NOT replaced."
+    exit 1
+fi
+
+# `mv` within the same filesystem is atomic.
+mv "$TMP_BINARY" "$INSTALL_DIR/$BINARY_NAME"
+# Leave the EXIT trap registered so $SMOKE_STDERR still gets cleaned;
+# `rm -f` on the moved-away $TMP_BINARY is a silent no-op.
 
-# Check if install directory is in PATH
+# Check PATH membership AND shadow (something else earlier in PATH).
 if [[ ":$PATH:" != *":$INSTALL_DIR:"* ]]; then
     echo ""
     echo "WARNING: $INSTALL_DIR is not in your PATH"
     echo "Add this to your shell profile (~/.bashrc or ~/.zshrc):"
     echo "  export PATH=\"\$PATH:$INSTALL_DIR\""
+else
+    PATH_RESOLVED="$(command -v lightpanda 2>/dev/null || true)"
+    if [ -n "$PATH_RESOLVED" ] && [ "$PATH_RESOLVED" != "$INSTALL_DIR/$BINARY_NAME" ]; then
+        echo ""
+        echo "WARNING: another 'lightpanda' is earlier in your PATH:"
+        echo "  $PATH_RESOLVED"
+        echo "Remove it or reorder PATH so $INSTALL_DIR takes precedence."
+    fi
 fi
 
-# Test installation
 echo ""
-echo "Testing Lightpanda..."
-if "$INSTALL_DIR/$BINARY_NAME" --version 2>/dev/null || "$INSTALL_DIR/$BINARY_NAME" --help 2>/dev/null | head -1; then
-    echo "Lightpanda installed successfully!"
-else
-    echo "Binary installed at: $INSTALL_DIR/$BINARY_NAME"
-fi
+echo "Lightpanda installed successfully: ${VERSION_OUT:-OK}"
 
 echo ""
 echo "=== Setup Complete ==="
