@join-pantheon/cli 0.31.2 → 0.32.0-rc.2

package/installer/install.sh

@@ -0,0 +1,612 @@
+#!/bin/sh
+# Pantheon installer for macOS and Linux.
+#
+#   curl -fsSL https://relay.joinpantheon.network/install.sh | sh -s -- join '<invite link>'
+#   curl -fsSL https://relay.joinpantheon.network/install.sh | sh -s -- start
+#   curl -fsSL https://relay.joinpantheon.network/install.sh | sh            (install only)
+#
+# What it does, and nothing else:
+#   1. downloads one pinned Node release from nodejs.org, checks its sha256
+#      against the sha256 pinned in this file (nodejs.org's own), and unpacks it into
+#      ~/.pantheon/runtime/node. That Node is Pantheon's own: a Node you already
+#      have is not touched, and nothing here depends on it.
+#   2. installs the Pantheon CLI with THAT Node's npm, into that same folder.
+#      No sudo, no system npm, nothing written outside your home folder.
+#   3. writes ~/.pantheon/bin/pantheon, which runs that Node by absolute path.
+#   4. puts ~/.pantheon/bin first on PATH in your shell profiles, in a block
+#      marked "# >>> pantheon >>>" that you can delete.
+#   5. runs `pantheon <the arguments you gave>`, reading answers from your
+#      terminal (stdin is the download, so it cannot be the keyboard).
+#
+# Running it again is safe: whatever is already right is left as it is. Two
+# copies at once are safe too: the second waits for the first.
+# The relay that serves this file fills in PANTHEON_VERSION below.
+
+set -eu
+
+PANTHEON_VERSION="__PANTHEON_VERSION__"
+NODE_VERSION="22.23.3"
+# The sha256 of every Node file this script may install, copied from nodejs.org's
+# SHASUMS256.txt for NODE_VERSION. A download is checked against THESE, never
+# against a sums file fetched beside it: a mirror (PANTHEON_NODE_MIRROR), or
+# anything between here and nodejs.org, could serve a file and a sums file that
+# agree with each other. Bumping NODE_VERSION means new pins: `node
+# scripts/node-pins.mjs` prints them, and release:check refuses stale ones.
+node_pin() {
+  case "$1" in
+    node-v22.23.3-darwin-arm64.tar.gz) echo 23b25245dcfb9af7262f8ff142e9e2e0af025368117329e7a7458a51e5922f53 ;;
+    node-v22.23.3-darwin-x64.tar.gz) echo 8a677b0219178efd6eb0e475457c4afb452b521a92f6e67845a73bd85727f2a8 ;;
+    node-v22.23.3-linux-arm64.tar.gz) echo 5ced2d48d1d7198739b7f86804de0171aefb6823b684b12341d3321afc3cb0b2 ;;
+    node-v22.23.3-linux-x64.tar.gz) echo 1084aa36196bba4c3a5e69a1ee388a6e4ff729dad09445fbcd434b28fe3c24af ;;
+    node-v22.23.3-linux-x64-musl.tar.gz) echo 633f49a4f388c5f9564d56d9c0f5ffa394346d92ca0076fe21cf776ece1988bc ;;
+    *) echo "" ;;
+  esac
+}
+# Another copy of nodejs.org/dist (a company mirror), if nodejs.org is blocked.
+NODE_DIST="${PANTHEON_NODE_MIRROR:-https://nodejs.org/dist}"
+SITE="https://relay.joinpantheon.network"
+
+STEP="starting"
+TMP_DIR=""
+SAID=0
+LOCK=""
+LOCKED=0
+
+# Every failure is one plain line: what failed, and what to do about it.
+fail() {
+  printf 'pantheon install failed: %s\n' "$*" >&2
+  SAID=1
+  exit 1
+}
+say() { printf '%s\n' "$*"; }
+note() { printf 'note: %s\n' "$*" >&2; }
+
+# Let go of the install lock, but only if it is still this installer's: a lock
+# taken over as stale while this one was stopped belongs to someone else now.
+unlock() {
+  if [ "$LOCKED" -eq 1 ]; then
+    LOCKED=0
+    case "$(cat "$LOCK/pid" 2>/dev/null || true)" in
+      "$$ "* | "") rm -rf "$LOCK" ;;
+    esac
+  fi
+}
+
+# shellcheck disable=SC2329 # run by the EXIT trap
+cleanup() {
+  status=$?
+  if [ -n "$TMP_DIR" ]; then
+    # Stopped between moving the old runtime aside and putting the new one in
+    # place: the old one goes back, so the pantheon command keeps working.
+    if [ -d "$TMP_DIR/old-node" ] && [ ! -e "$NODE_DIR" ]; then mv "$TMP_DIR/old-node" "$NODE_DIR" 2>/dev/null || true; fi
+    rm -rf "$TMP_DIR"
+  fi
+  unlock
+  # set -e stopped on something no check above anticipated: still one line.
+  if [ "$status" -ne 0 ] && [ "$SAID" -eq 0 ]; then
+    printf 'pantheon install failed while %s (exit %s). Run the same command again; if it fails the same way, send this line to sid@joinpantheon.network\n' "$STEP" "$status" >&2
+  fi
+}
+trap cleanup EXIT
+# shellcheck disable=SC2329 # run by the INT/TERM/HUP trap
+stopped() { SAID=1; printf 'pantheon install stopped.\n' >&2; exit 130; }
+# Ctrl-C, a closed terminal, a kill: the EXIT trap above still runs, so the
+# temporary folder and the lock go with it, and the next run starts clean.
+trap stopped INT TERM HUP
+
+case "$PANTHEON_VERSION" in
+  *__*) fail "this copy of install.sh has no version filled in. Use the one the relay serves: curl -fsSL $SITE/install.sh | sh" ;;
+esac
+
+# ---- what this machine is --------------------------------------------------
+
+STEP="checking this machine"
+[ -n "${HOME:-}" ] || fail "HOME is not set, so there is nowhere to install. Run this from your own login shell."
+if [ "$(id -u)" = "0" ] && [ -n "${SUDO_USER:-}" ]; then
+  fail "do not run this with sudo: it needs no admin rights and installs into your home folder. Run it again without sudo."
+fi
+
+for tool in uname tar gzip mktemp awk sed; do
+  command -v "$tool" >/dev/null 2>&1 || fail "'$tool' is missing on this machine. Install it with your package manager, then run this again."
+done
+command -v curl >/dev/null 2>&1 || fail "curl is missing. Install it (Debian/Ubuntu: sudo apt-get install -y curl ca-certificates; Fedora: sudo dnf install -y curl; Alpine: apk add curl), then run this again."
+if command -v sha256sum >/dev/null 2>&1; then
+  sha256() { sha256sum "$1" | awk '{print $1}'; }
+elif command -v shasum >/dev/null 2>&1; then
+  sha256() { shasum -a 256 "$1" | awk '{print $1}'; }
+else
+  fail "neither sha256sum nor shasum is available to check the download. Install coreutils (or perl's shasum), then run this again."
+fi
+
+case "$(uname -s)" in
+  Darwin) node_os=darwin ;;
+  Linux) node_os=linux ;;
+  *) fail "this installer is for macOS and Linux. On Windows, in PowerShell: irm $SITE/install.ps1 | iex" ;;
+esac
+case "$(uname -m)" in
+  x86_64 | amd64) node_arch=x64 ;;
+  arm64 | aarch64) node_arch=arm64 ;;
+  *) fail "this processor ($(uname -m)) has no Node $NODE_VERSION build. Pantheon runs on x64 and arm64." ;;
+esac
+# A Terminal running under Rosetta reports x86_64 on an Apple-silicon Mac; the
+# native build is the right one there.
+if [ "$node_os" = darwin ] && [ "$node_arch" = x64 ] && [ "$(sysctl -n sysctl.proc_translated 2>/dev/null || echo 0)" = 1 ]; then
+  node_arch=arm64
+fi
+# Alpine and other musl systems cannot run the glibc build at all.
+libc=""
+if [ "$node_os" = linux ] && ls /lib/ld-musl-* >/dev/null 2>&1; then
+  [ "$node_arch" = x64 ] || fail "this is a musl Linux (Alpine) on arm64, which has no Node $NODE_VERSION build. Install Node 22.13+ yourself, then: npm install -g @join-pantheon/cli@$PANTHEON_VERSION"
+  libc="-musl"
+fi
+
+# A container or a cloud workspace can install Pantheon, but what it installs
+# goes away with the session, and the menu bar, alerts and the worker belong on
+# the computer the person sits at. The same signals as src/host-env.ts.
+container_evidence() {
+  [ "$node_os" = linux ] || return 0
+  for v in CODESPACES CLOUDENV_ENVIRONMENT_ID REMOTE_CONTAINERS REMOTE_CONTAINERS_IPC DEVCONTAINER GITPOD_WORKSPACE_ID CLOUD_SHELL REPL_ID KUBERNETES_SERVICE_HOST container; do
+    eval "val=\${$v:-}"
+    if [ -n "$val" ]; then printf '$%s is set; ' "$v"; fi
+  done
+  [ -e /.dockerenv ] && printf '/.dockerenv exists; '
+  [ -e /run/.containerenv ] && printf '/run/.containerenv exists; '
+  [ -e /var/run/secrets/kubernetes.io ] && printf 'a Kubernetes pod; '
+  wsl=0
+  { [ -n "${WSL_DISTRO_NAME:-}" ] || grep -qi microsoft /proc/version 2>/dev/null; } && wsl=1
+  cg=$(cat /proc/1/cgroup 2>/dev/null || true)
+  case "$cg" in
+    *docker* | *containerd* | *kubepods* | *lxc* | *libpod* | *crio*) printf 'pid 1 is in a container cgroup; ' ;;
+    "0::/") [ "$wsl" = 1 ] || printf 'pid 1 is at the root of its own cgroup namespace; ' ;;
+  esac
+  comm=$(cat /proc/1/comm 2>/dev/null || true)
+  case "$comm" in
+    "" | systemd | init | openrc-init | runit | runit-init | launchd | dinit | s6-svscan | s6-linux-init | shepherd) ;;
+    *) printf 'pid 1 is "%s", not an init system; ' "$comm" ;;
+  esac
+  grep -qi gvisor /proc/version 2>/dev/null && printf 'the kernel is gVisor; '
+  root=$(awk '$5 == "/" { for (i = 6; i <= NF; i++) if ($i == "-") { print $(i+1) " " $(i+2); exit } }' /proc/1/mountinfo 2>/dev/null || true)
+  case "$root" in
+    "overlay "* | "overlayfs "* | "9p "* | "virtiofs "* | "aufs "*)
+      case "$root" in *composefs*) ;; *) [ -e /run/ostree-booted ] || printf 'the root filesystem is %s; ' "${root%% *}" ;; esac ;;
+  esac
+  return 0
+}
+evidence=$(container_evidence)
+if [ -n "$evidence" ]; then
+  note "this looks like a container or cloud workspace, not the computer you work on (${evidence%; }). Pantheon will install, but it goes away with this session, and the menu bar, alerts and the worker need your own computer."
+fi
+
+# Both spellings, so curl, npm and Pantheon itself all see the same proxy.
+for pair in "HTTPS_PROXY https_proxy" "HTTP_PROXY http_proxy" "NO_PROXY no_proxy"; do
+  up=${pair% *}; low=${pair#* }
+  eval "uv=\${$up:-}; lv=\${$low:-}"
+  if [ -n "$lv" ] && [ -z "$uv" ]; then eval "$up=\$lv; export $up"; fi
+  if [ -n "$uv" ] && [ -z "$lv" ]; then eval "$low=\$uv; export $low"; fi
+done
+
+ROOT="$HOME/.pantheon"
+RUNTIME="$ROOT/runtime"
+NODE_DIR="$RUNTIME/node"
+NODE="$NODE_DIR/bin/node"
+PKG_DIR="$NODE_DIR/lib/node_modules/@join-pantheon/cli"
+BIN_DIR="$ROOT/bin"
+LAUNCHER="$BIN_DIR/pantheon"
+LOG="$ROOT/logs/install.log"
+
+STEP="creating $ROOT"
+# The first of Pantheon's folders (or the runtime's files) that belongs to
+# someone else: what an earlier `sudo pantheon` or `sudo npm` leaves behind.
+# Nothing when find is missing; the steps below then say what failed.
+foreign() {
+  me=$(id -u)
+  for d in "$ROOT" "$RUNTIME" "$BIN_DIR" "$ROOT/logs"; do
+    if [ -e "$d" ]; then
+      f=$(find "$d" -maxdepth 1 ! -user "$me" 2>/dev/null | head -n 1)
+      if [ -n "$f" ]; then printf '%s' "$f"; return 0; fi
+    fi
+  done
+  if [ -d "$NODE_DIR" ]; then find "$NODE_DIR" ! -user "$me" 2>/dev/null | head -n 1; fi
+}
+not_ours() {
+  # shellcheck disable=SC2012 # the owner's name, which stat spells differently on macOS and Linux
+  fail "$1 belongs to $(ls -ld "$1" | awk '{print $3}'), not to you (left by an earlier install run with sudo). Give it back with: sudo chown -R $(id -un) \"$ROOT\" then run this again."
+}
+if ! mkdir -p "$RUNTIME" "$BIN_DIR" "$ROOT/logs" 2>/dev/null; then
+  f=$(foreign)
+  [ -n "$f" ] && not_ours "$f"
+  fail "could not create $RUNTIME. Check that your home folder is writable by you (ls -ld \"$HOME\"), then run this again."
+fi
+f=$(foreign)
+[ -n "$f" ] && not_ours "$f"
+
+# ---- one installer at a time ----------------------------------------------
+
+# Two installers at once (a second terminal, a link pasted twice) would swap
+# the runtime under each other. mkdir is atomic, so the lock is a folder; it
+# holds the holder's pid and machine name. The second installer waits for the
+# first, then finds everything in place. A lock whose holder is gone (killed,
+# the machine lost power) is stale and taken over, through a second folder, so
+# two installers that find the same stale lock cannot both take it.
+LOCK="$RUNTIME/.install.lock"
+STEP="waiting for another Pantheon install"
+host=$(uname -n 2>/dev/null || echo unknown)
+# Whether $1 is older than $2 minutes (false when it cannot tell).
+older_than() { [ -n "$(find "$1" -maxdepth 0 -mmin +"$2" 2>/dev/null)" ]; }
+lock_stale() {
+  holder=$(cat "$LOCK/pid" 2>/dev/null || true)
+  [ -d "$LOCK" ] || return 1
+  # An hour is far past any real install: a pid reused since, or a holder on
+  # another machine sharing this home folder, cannot keep the lock forever.
+  older_than "$LOCK" 60 && return 0
+  # Being taken right now (the pid not written yet), unless that was long ago.
+  [ -n "$holder" ] || { older_than "$LOCK" 1; return; }
+  hpid=${holder%% *}
+  case "$hpid" in "" | *[!0-9]*) return 0 ;; esac
+  [ "${holder#* }" = "$host" ] || return 1
+  ! kill -0 "$hpid" 2>/dev/null
+}
+waited=0
+until mkdir "$LOCK" 2>/dev/null; do
+  [ -d "$RUNTIME" ] || fail "could not create $RUNTIME. Check that your home folder is writable by you, then run this again."
+  if lock_stale; then
+    if mkdir "$LOCK.break" 2>/dev/null; then
+      # Checked again while holding the break folder: only a lock still stale
+      # now is removed, never one a live installer took a moment ago.
+      lock_stale && rm -rf "$LOCK"
+      rmdir "$LOCK.break" 2>/dev/null || true
+    elif older_than "$LOCK.break" 1; then
+      rm -rf "$LOCK.break"
+    else
+      sleep 1
+    fi
+    continue
+  fi
+  holder=$(cat "$LOCK/pid" 2>/dev/null || true)
+  if [ "$waited" -eq 0 ]; then say "Another Pantheon install is running${holder:+ (pid ${holder%% *})}; waiting for it to finish..."; fi
+  [ "$waited" -ge 600 ] && fail "another Pantheon install${holder:+ (pid ${holder%% *})} has been running for over 10 minutes. Let it finish or stop it, then run this again."
+  sleep 1
+  waited=$((waited + 1))
+done
+LOCKED=1
+printf '%s %s\n' "$$" "$host" >"$LOCK/pid" 2>/dev/null || true
+
+# What an installer stopped by kill -9 or a power cut left behind.
+find "$RUNTIME" -maxdepth 1 -type d -name '.install.??????' -exec rm -rf {} + 2>/dev/null || true
+
+STEP="creating $ROOT"
+TMP_DIR=$(mktemp -d "$RUNTIME/.install.XXXXXX") || fail "could not make a temporary folder in $RUNTIME. Check free disk space, then run this again."
+
+# Download $1 to $2. curl's own complaint goes into the one line, not above it.
+fetch() {
+  if ! curl -fsSL --retry 3 --connect-timeout 20 -o "$2" "$1" 2>"$TMP_DIR/curl.err"; then
+    why=$(tr '\n' ' ' <"$TMP_DIR/curl.err" | sed 's/  *$//')
+    fail "could not download $1 (${why:-no answer}). Check your internet connection; behind a proxy set HTTPS_PROXY; then run this again."
+  fi
+}
+
+# ---- 1. Pantheon's own Node -----------------------------------------------
+
+have_node=""
+if [ -x "$NODE" ]; then have_node=$("$NODE" --version 2>/dev/null || true); fi
+if [ "$have_node" = "v$NODE_VERSION" ]; then
+  say "Node v$NODE_VERSION for Pantheon is already in $NODE_DIR."
+else
+  STEP="downloading Node v$NODE_VERSION"
+  tarball="node-v$NODE_VERSION-$node_os-$node_arch$libc.tar.gz"
+  say "Downloading Node v$NODE_VERSION for Pantheon ($node_os-$node_arch$libc)..."
+  want=$(node_pin "$tarball")
+  [ -n "$want" ] || fail "this installer has no checksum for $tarball, so it cannot install Node here. Install Node 22.13+ yourself, then: npm install -g @join-pantheon/cli@$PANTHEON_VERSION"
+  fetch "$NODE_DIST/v$NODE_VERSION/$tarball" "$TMP_DIR/$tarball"
+
+  STEP="checking the Node download"
+  got=$(sha256 "$TMP_DIR/$tarball")
+  [ "$got" = "$want" ] || fail "the Node download does not match its published sha256 (expected $want, got $got), so it was not used: it arrived incomplete or was changed on the way. Run this again; if it repeats, try another network."
+
+  STEP="unpacking Node"
+  mkdir "$TMP_DIR/unpack" || fail "could not make a folder in $TMP_DIR. Check free disk space in $HOME, then run this again."
+  if ! tar -xzf "$TMP_DIR/$tarball" -C "$TMP_DIR/unpack" 2>"$TMP_DIR/tar.err"; then
+    why=$(head -n 1 "$TMP_DIR/tar.err" 2>/dev/null || true)
+    case "$why" in
+      *[Ss]pace* | *quota* | *"Cannot write"* | *"Write error"*) fail "could not unpack $tarball ($why). Free some disk space in $HOME, then run this again." ;;
+      *) fail "could not unpack $tarball (${why:-tar failed}). Free disk space in $HOME if it is full, then run this again." ;;
+    esac
+  fi
+  mv "$TMP_DIR/unpack/node-v$NODE_VERSION-$node_os-$node_arch$libc" "$TMP_DIR/node" || fail "the Node archive did not have the layout expected. Run this again; if it repeats, send this line to sid@joinpantheon.network"
+  if ! "$TMP_DIR/node/bin/node" --version >/dev/null 2>&1; then
+    # musl's Node build needs the C++ runtime, which a bare Alpine lacks.
+    [ -n "$libc" ] && fail "Node v$NODE_VERSION needs the C++ runtime on Alpine. Install it (apk add libstdc++), then run this again."
+    fail "Node v$NODE_VERSION does not run on this system (Linux needs glibc 2.28 or newer: Debian 10, Ubuntu 20.04, RHEL 8 or later). Install Node 22.13+ yourself, then: npm install -g @join-pantheon/cli@$PANTHEON_VERSION"
+  fi
+
+  # The CLI from the old runtime moves into the new one with it, so the
+  # pantheon command keeps working until npm below has run.
+  if [ -d "$NODE_DIR/lib/node_modules/@join-pantheon" ]; then
+    mkdir -p "$TMP_DIR/node/lib/node_modules"
+    cp -R "$NODE_DIR/lib/node_modules/@join-pantheon" "$TMP_DIR/node/lib/node_modules/" 2>/dev/null || true
+  fi
+
+  # Swapped by rename, never unpacked over: a half-written runtime is never
+  # the one a running service or a new terminal starts.
+  # Ctrl-C waits for the two renames: between them there is no runtime at all.
+  STEP="putting Node in place"
+  trap '' INT TERM HUP
+  if [ -e "$NODE_DIR" ]; then mv "$NODE_DIR" "$TMP_DIR/old-node" || fail "could not move the old $NODE_DIR aside. Quit anything using it (pantheon service stop worker), then run this again."; fi
+  if ! mv "$TMP_DIR/node" "$NODE_DIR"; then
+    [ -e "$TMP_DIR/old-node" ] && mv "$TMP_DIR/old-node" "$NODE_DIR"
+    fail "could not put the new Node in $NODE_DIR. Check free disk space and permissions, then run this again."
+  fi
+  trap stopped INT TERM HUP
+  say "Node v$NODE_VERSION is in $NODE_DIR."
+fi
+
+# The system's certificate store, as well as Node's own: on a network that
+# inspects secure traffic, the company's root is only there. npm needs it to
+# install, and pantheon needs it to reach its relay, so the launcher below runs
+# Node with it too (when this Node has the flag; the pinned one does).
+ca=""
+if "$NODE" --use-system-ca -e 0 >/dev/null 2>&1; then ca="--use-system-ca"; fi
+
+# ---- 2. the Pantheon CLI, with that Node's own npm ------------------------
+
+# The version of the CLI in the runtime, but only when it is whole: its
+# package.json names that version AND it starts and says so. A run stopped
+# halfway through npm can leave the first without the second; that is
+# installed again, never called done.
+installed_cli() {
+  if [ -f "$PKG_DIR/package.json" ] && [ -f "$PKG_DIR/bin/pantheon.js" ]; then
+    v=$("$NODE" -e 'try { process.stdout.write(require(process.argv[1]).version || "") } catch {}' "$PKG_DIR/package.json" 2>/dev/null || true)
+    if [ -n "$v" ] && [ "$("$NODE" "$PKG_DIR/bin/pantheon.js" --version 2>/dev/null </dev/null || true)" = "$v" ]; then printf '%s' "$v"; fi
+  fi
+  return 0
+}
+
+# What npm installs. PANTHEON_INSTALL_SPEC swaps the registry package for a
+# package file on this machine, so a release candidate goes through this exact
+# script (scripts/installer-tests does) before its version is on npm. Only a
+# full path to a local .tgz is taken: no URL, git or registry spec, so it can
+# never send an install anywhere npm would not have gone. Whoever can set it can
+# already set npm_config_registry, NODE_OPTIONS or PATH for this shell, so it
+# opens no new way in; and the file must hold PANTHEON_VERSION itself, so it
+# cannot install a different release than the one this script names.
+spec="@join-pantheon/cli@$PANTHEON_VERSION"
+if [ -n "${PANTHEON_INSTALL_SPEC:-}" ]; then
+  case "$PANTHEON_INSTALL_SPEC" in
+    /*.tgz) [ -f "$PANTHEON_INSTALL_SPEC" ] || fail "PANTHEON_INSTALL_SPEC is $PANTHEON_INSTALL_SPEC, which is not a file. Unset it to install from npm." ;;
+    *) fail "PANTHEON_INSTALL_SPEC must be the full path of a package .tgz on this machine, not $PANTHEON_INSTALL_SPEC. Unset it to install from npm." ;;
+  esac
+  file_version=$(tar -xzOf "$PANTHEON_INSTALL_SPEC" package/package.json 2>/dev/null | "$NODE" -e 'let s = ""; process.stdin.on("data", (d) => { s += d; }).on("end", () => { try { process.stdout.write(JSON.parse(s).version || "") } catch {} })' 2>/dev/null || true)
+  [ "$file_version" = "$PANTHEON_VERSION" ] || fail "PANTHEON_INSTALL_SPEC holds Pantheon ${file_version:-of no version}, not $PANTHEON_VERSION. Use the package built for $PANTHEON_VERSION, or unset it to install from npm."
+  spec=$PANTHEON_INSTALL_SPEC
+  note "installing Pantheon $PANTHEON_VERSION from $spec, not from npm (PANTHEON_INSTALL_SPEC is set)."
+fi
+
+have_cli=$(installed_cli)
+if [ "$have_cli" = "$PANTHEON_VERSION" ]; then
+  say "Pantheon $PANTHEON_VERSION is already installed."
+else
+  STEP="installing Pantheon $PANTHEON_VERSION"
+  say "Installing Pantheon $PANTHEON_VERSION..."
+  # A registry that does not answer fails in about two minutes, not npm's six
+  # (--fetch-timeout/--fetch-retries): long enough for a slow network.
+  # npm runs as `node npm-cli.js`, so its `#!/usr/bin/env node` never picks up
+  # some other node; the prefix is named, so a prefix= in ~/.npmrc or
+  # NPM_CONFIG_PREFIX cannot send the package elsewhere; and the cache is
+  # Pantheon's own, so a ~/.npm left root-owned by an old `sudo npm` cannot
+  # fail it with EACCES. $ca (above) trusts the same certificates curl just
+  # did, which is what a TLS-inspecting company proxy needs.
+  if ! PATH="$NODE_DIR/bin:$PATH" "$NODE" ${ca:+"$ca"} "$NODE_DIR/lib/node_modules/npm/bin/npm-cli.js" install -g \
+      --prefix "$NODE_DIR" --cache "$RUNTIME/npm-cache" \
+      "$spec" --no-audit --no-fund --loglevel=error --fetch-timeout=60000 --fetch-retries=2 >"$LOG" 2>&1; then
+    # npm's first two error lines (`code E404`, `404 Not Found - GET ...`) say why.
+    why=$(grep -E '^npm (error|ERR!) ' "$LOG" | head -n 2 | sed -e 's/^npm error //' -e 's/^npm ERR! //' | tr '\n' ';' | sed 's/;$//; s/;/; /g' || true)
+    [ -n "$why" ] || why=$(grep -m 1 -i 'error' "$LOG" || true)
+    # A full disk can also leave the log itself empty, so free space is asked too.
+    free=$(df -Pk "$RUNTIME" 2>/dev/null | awk 'NR == 2 { print $4 }' || true)
+    if grep -q 'ENOSPC' "$LOG" 2>/dev/null || { [ -n "$free" ] && [ "$free" -lt 20480 ] 2>/dev/null; }; then
+      fail "npm could not install @join-pantheon/cli@$PANTHEON_VERSION because the disk is full (${why:-ENOSPC}). Free some disk space in $HOME, then run this again."
+    fi
+    fail "npm could not install @join-pantheon/cli@$PANTHEON_VERSION (${why:-see the log}). Behind a proxy, set HTTPS_PROXY; if your network inspects TLS, set NODE_EXTRA_CA_CERTS to your company's CA file. Full log: $LOG"
+  fi
+  [ -f "$PKG_DIR/bin/pantheon.js" ] || fail "npm finished but $PKG_DIR/bin/pantheon.js is not there. Full log: $LOG (send it to sid@joinpantheon.network)"
+  have_cli=$(installed_cli)
+  [ "$have_cli" = "$PANTHEON_VERSION" ] || fail "npm finished, but the Pantheon in $PKG_DIR does not start as $PANTHEON_VERSION${have_cli:+ (it is $have_cli)}. Run the same command again; if it fails the same way, send this line and $LOG to sid@joinpantheon.network"
+  say "Pantheon $PANTHEON_VERSION is installed."
+fi
+
+# ---- 3. the launcher -------------------------------------------------------
+
+# Whether two files hold the same bytes (false when either is missing, or cmp is).
+same() { cmp -s "$1" "$2" 2>/dev/null; }
+
+# A path as one single-quoted shell word.
+shq() { printf "'%s'" "$(printf '%s' "$1" | sed "s/'/'\\\\''/g")"; }
+
+STEP="writing $LAUNCHER"
+{
+  printf '#!/bin/sh\n'
+  printf '# The pantheon command, written by the Pantheon installer. It runs\n'
+  printf "# Pantheon's own Node by absolute path, so it never depends on which\n"
+  printf '# node comes first on PATH. Running the installer again rewrites it.\n'
+  printf 'exec %s %s%s "$@"\n' "$(shq "$NODE")" "${ca:+$ca }" "$(shq "$PKG_DIR/bin/pantheon.js")"
+} >"$TMP_DIR/launcher" || fail "could not write the pantheon command. Check free disk space, then run this again."
+chmod 755 "$TMP_DIR/launcher"
+if ! same "$TMP_DIR/launcher" "$LAUNCHER"; then
+  mv -f "$TMP_DIR/launcher" "$LAUNCHER" || fail "could not write $LAUNCHER. Check that $BIN_DIR is writable by you, then run this again."
+fi
+"$LAUNCHER" --version >/dev/null 2>&1 || fail "the installed pantheon does not start ($LAUNCHER --version failed). Run the same command again; if it fails the same way, send this line to sid@joinpantheon.network"
+
+# ---- 4. PATH ---------------------------------------------------------------
+
+STEP="adding $BIN_DIR to PATH"
+BEGIN_MARK='# >>> pantheon >>>'
+END_MARK='# <<< pantheon <<<'
+# shellcheck disable=SC2016 # written literally: the profile expands it, not this script
+posix_block() {
+  printf '%s\n' "$BEGIN_MARK"
+  printf '%s\n' '# The pantheon command, first on PATH. Written by the Pantheon installer; delete this block to undo.'
+  printf '%s\n' 'case "$PATH" in'
+  printf '%s\n' '  "$HOME/.pantheon/bin:"*) ;;'
+  printf '%s\n' '  *) export PATH="$HOME/.pantheon/bin:$PATH" ;;'
+  printf '%s\n' 'esac'
+  printf '%s\n' "$END_MARK"
+}
+
+# Replace the contents of profile $1 with $TMP_DIR/new. In place (cat >), so a
+# dotfile that is a symlink stays one and keeps its owner and mode. Ctrl-C
+# waits for it, and a write that fails halfway (a full disk) puts the old
+# contents back: a profile is never left cut short.
+write_over() {
+  trap '' INT TERM HUP
+  ok=0
+  if [ -e "$1" ]; then cp "$1" "$TMP_DIR/orig" 2>/dev/null || ok=1; fi
+  if [ "$ok" -eq 0 ] && ! cat "$TMP_DIR/new" >"$1" 2>/dev/null; then
+    ok=1
+    if [ -f "$TMP_DIR/orig" ]; then cat "$TMP_DIR/orig" >"$1" 2>/dev/null || true; fi
+  fi
+  rm -f "$TMP_DIR/orig"
+  trap stopped INT TERM HUP
+  return "$ok"
+}
+
+# Put the block in one profile, or bring an older block up to date in the
+# same place. Every other line of the file is kept as it was.
+added=""
+add_block() {
+  f=$1
+  posix_block >"$TMP_DIR/block"
+  begins=0
+  ends=0
+  if [ -f "$f" ]; then
+    begins=$(grep -cxF "$BEGIN_MARK" "$f" 2>/dev/null || true)
+    ends=$(grep -cxF "$END_MARK" "$f" 2>/dev/null || true)
+  fi
+  # A marker without its pair (edited by hand, or cut short): rewriting from
+  # it could take the lines after it too, so the file is not touched.
+  if [ "${begins:-0}" -ne "${ends:-0}" ] || [ "${begins:-0}" -gt 1 ]; then
+    note "the pantheon block in $f has a marker line without its pair, so $f was left as it is; put $BIN_DIR at the front of PATH there yourself"
+    return 0
+  fi
+  if [ "${begins:-0}" -eq 1 ]; then
+    awk -v b="$BEGIN_MARK" -v e="$END_MARK" '$0 == b { keep = 1 } keep { print } $0 == e { keep = 0 }' "$f" >"$TMP_DIR/old"
+    same "$TMP_DIR/old" "$TMP_DIR/block" && return 0
+    awk -v b="$BEGIN_MARK" -v e="$END_MARK" -v nf="$TMP_DIR/block" '
+      $0 == b { while ((getline l < nf) > 0) print l; skip = 1; next }
+      $0 == e && skip { skip = 0; next }
+      !skip { print }' "$f" >"$TMP_DIR/new" || { note "could not update $f; put $BIN_DIR at the front of PATH there yourself"; return 0; }
+  else
+    {
+      if [ -s "$f" ]; then
+        cat "$f"
+        # A last line without its newline, then one blank line before ours.
+        if [ -n "$(tail -c 1 "$f")" ]; then printf '\n'; fi
+        printf '\n'
+      fi
+      cat "$TMP_DIR/block"
+    } >"$TMP_DIR/new" 2>/dev/null || { note "could not read $f; put $BIN_DIR at the front of PATH there yourself"; return 0; }
+  fi
+  write_over "$f" || { note "could not write $f; put $BIN_DIR at the front of PATH there yourself"; return 0; }
+  added="$added ${f#"$HOME"/}"
+}
+
+login_shell=$(basename "${SHELL:-sh}")
+# ~/.profile: read by sh and dash logins, by bash when it has no .bash_profile,
+# and by the `sh -lc` Pantheon itself uses to find programs.
+add_block "$HOME/.profile"
+[ -f "$HOME/.bash_profile" ] && add_block "$HOME/.bash_profile"
+{ [ -f "$HOME/.bashrc" ] || [ "$login_shell" = bash ]; } && add_block "$HOME/.bashrc"
+{ [ -f "$HOME/.zshrc" ] || [ "$login_shell" = zsh ]; } && add_block "$HOME/.zshrc"
+[ -f "$HOME/.zprofile" ] && add_block "$HOME/.zprofile"
+# fish reads its own conf.d folder; the file there is ours whole.
+if command -v fish >/dev/null 2>&1 || [ -d "$HOME/.config/fish" ]; then
+  fish_conf="$HOME/.config/fish/conf.d/pantheon.fish"
+  # shellcheck disable=SC2016 # written literally: fish expands it, not this script
+  {
+    printf '%s\n' '# The pantheon command, first on PATH. Written by the Pantheon installer; delete this file to undo.'
+    printf '%s\n' 'set -l pantheon_bin $HOME/.pantheon/bin'
+    printf '%s\n' 'set -gx PATH $pantheon_bin (string match -v -- $pantheon_bin $PATH)'
+  } >"$TMP_DIR/fish"
+  if ! same "$TMP_DIR/fish" "$fish_conf"; then
+    if mkdir -p "$HOME/.config/fish/conf.d" 2>/dev/null && cat "$TMP_DIR/fish" >"$fish_conf" 2>/dev/null; then
+      added="$added ${fish_conf#"$HOME"/}"
+    else
+      note "could not write $fish_conf; add $BIN_DIR to the front of PATH in fish yourself"
+    fi
+  fi
+fi
+[ -n "$added" ] && say "Put $BIN_DIR first on PATH in:$added"
+
+# An older pantheon (npm -g, Homebrew, a checkout) is left exactly as it is.
+other=$(command -v pantheon 2>/dev/null || true)
+if [ -n "$other" ] && [ "$other" != "$LAUNCHER" ]; then
+  note "another pantheon is installed at $other and was left as it is. New terminals run $LAUNCHER first."
+fi
+
+# ---- 5. hand over to pantheon ----------------------------------------------
+
+rm -rf "$TMP_DIR"
+TMP_DIR=""
+unlock
+trap - EXIT INT TERM HUP
+
+if [ "$#" -eq 0 ]; then
+  say ""
+  say "Pantheon $PANTHEON_VERSION is installed. Open a new terminal (or run: export PATH=\"$BIN_DIR:\$PATH\"), then:"
+  say "  pantheon start                    create a team"
+  say "  pantheon join '<invite link>'     join a teammate's team"
+  exit 0
+fi
+
+say ""
+# Found first by anything pantheon starts during setup, before any new terminal.
+PATH="$BIN_DIR:$PATH"
+export PATH
+# stdin is the curl pipe; sign-in and setup questions must come from the
+# keyboard.
+if (: </dev/tty) 2>/dev/null; then
+  exec "$LAUNCHER" "$@" </dev/tty
+fi
+if [ -t 0 ]; then exec "$LAUNCHER" "$@"; fi
+
+# No terminal at all: CI, a pipe, some IDE task runners. pantheon still runs,
+# because it never asks a question without one (every prompt checks
+# process.stdin.isTTY first) and works on flags alone: a join to a self-hosted
+# relay, or from a machine already signed in, needs no answers. stdin is
+# /dev/null rather than the rest of the curl pipe, so nothing can wait on it.
+#
+# What it cannot do here is sign in. On the hosted relay (or one of a team's
+# own that verifies email) join and start then stop at once, before anything
+# is changed, with "sign in first" (or the relay's NOT_SIGNED_IN). When that is
+# how it ended, and config.json still has no account, the last line says the
+# one thing to do. Any other failure (a mistyped link, an expired invite) keeps
+# pantheon's own words as the last line, since a terminal would not fix it.
+code=0
+said=$(mktemp 2>/dev/null || true)
+if [ -n "$said" ]; then
+  # pantheon's stderr is shown as it comes and kept, to read its reason after.
+  { { "$LAUNCHER" "$@" </dev/null 3>&- || echo "$?" >"$said.code"; } 2>&1 1>&3 | tee "$said" >&2; } 3>&1
+  if [ -f "$said.code" ]; then code=$(cat "$said.code"); fi
+else
+  "$LAUNCHER" "$@" </dev/null || code=$?
+fi
+if [ "$code" -ne 0 ] && [ -n "$said" ] && grep -qE 'sign in first|NOT_SIGNED_IN' "$said" 2>/dev/null; then
+  case "$1" in
+    join | start)
+      cfg="${PANTHEON_HOME:-$HOME/.pantheon}/config.json"
+      if ! "$NODE" -e 'try { process.exit(JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).account ? 0 : 1) } catch { process.exit(1) }' "$cfg" 2>/dev/null; then
+        line="pantheon"
+        # Quoted only where a shell needs it, so it reads as the person typed it.
+        for a in "$@"; do
+          case "$a" in
+            "" | *[!A-Za-z0-9_./:=@%+,-]*) line="$line $(shq "$a")" ;;
+            *) line="$line $a" ;;
+          esac
+        done
+        if [ "$1" = join ]; then what="joining"; else what="creating your team"; fi
+        printf '\nPantheon is installed. To finish %s, open a terminal and run: %s\n' "$what" "$line" >&2
+      fi
+      ;;
+  esac
+fi
+if [ -n "$said" ]; then rm -f "$said" "$said.code"; fi
+exit "$code"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@join-pantheon/cli",
-  "version": "0.31.2",
+  "version": "0.32.0-rc.2",
   "description": "Let your coding agent collaborate directly with your teammates' agents — ask, agree an interface, and deliver, without a human relaying messages.",
   "type": "module",
   "bin": {
@@ -15,10 +15,13 @@
     "relay": "node dist/cli.js relay",
     "test": "PANTHEON_HOME=\"$(mktemp -d)\" HOME=\"$(mktemp -d)\" node --test --test-force-exit dist/test/*.test.js",
     "prepare": "npm run build",
-    "prepublishOnly": "npm run build && npm test",
+    "build:helpers": "node scripts/build-helpers.mjs",
+    "release:check": "node scripts/release-check.mjs",
+    "prepublishOnly": "npm run build && npm run build:helpers && npm test && npm run release:check",
     "start": "node dist/cli.js relay",
     "test:ci": "node scripts/test.mjs",
-    "smoke": "node scripts/smoke.mjs"
+    "smoke": "node scripts/smoke.mjs",
+    "test:installer": "node scripts/installer-tests/run.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
@@ -35,6 +38,8 @@
     "bin",
     "dist",
     "helper",
+    "installer",
+    "helper/macos/prebuilt/",
     "!dist/test",
     "!dist/**/*.map",
     "README.md",