@basein/runner 0.2.8 → 0.2.10

package/scripts/install.sh

@@ -0,0 +1,586 @@
+#!/bin/sh
+#
+# BaseIn runner — one-line setup for macOS and Linux.
+#
+#   curl -fsSL https://api.bi2202.com/install.sh | BIR_SETUP_TOKEN="<token>" sh
+#
+# Paste that in a terminal opened in the project you start Claude Code in (the
+# console's "Set up the runner" page mints the token). When it finishes, `claude`
+# in that folder is recorded and replayed, and nothing has to stay open.
+#
+# What it does, in order — every step prints a "==> …" line:
+#
+#   0. refuses the home folder and the root of the disk, before anything is
+#      downloaded (BIR_PROJECT=<dir> points it somewhere else);
+#   1. Node: the machine's `node` when it is >= 20, has npm next to it and is not
+#      managed by a version manager (nvm, fnm, Volta, asdf, mise, nodenv — their
+#      paths change per shell or per version, and the recorder's SessionStart hook
+#      pins an absolute path); otherwise a private Node 24.21.0 is downloaded into
+#      ~/.baseinstrunner/node/v<V>/, checked against the digests embedded below.
+#      The private Node is never put on PATH;
+#   2. the runner: @basein/runner into ~/.baseinstrunner/npm, always through
+#      npm-cli.js and never into the machine's npm prefix (no sudo, ever); then
+#      launchers `bir` and `bir-hooks` in ~/.baseinstrunner/bin and one PATH line
+#      in the shell profile;
+#   3. Claude Code, through its official installer, when `claude` is missing;
+#   4. `bir setup`: signs in with the token (or the cached session, or the
+#      browser), wires the project and starts the recorder in the background.
+#
+# Safe to re-run; re-running is also the upgrade path. To record another project
+# later: cd there and run `bir setup` (no token needed, the sign-in is kept).
+#
+# Environment:
+#   BIR_SETUP_TOKEN    one-time setup token from the console. Copied and removed
+#                      from the environment as the first thing this script does;
+#                      only the `bir setup` child ever sees it.
+#   BIR_AUTH_URL       the API address. Needed only when this is the raw file from
+#                      the repository — the copy the API serves has it filled in.
+#   BIR_VERSION        runner version to install (default: the served one, else latest).
+#   BIR_PROJECT        the project directory (default: the current one).
+#   BIR_NODE_VERSION   private Node version (default 24.21.0). Any other version
+#                      is verified against nodejs.org's SHASUMS256.txt instead of
+#                      the embedded digests.
+#   BIR_NODE_ARCHIVE   a node-v<V>-<os>-<arch>.tar.gz already on disk, used instead
+#                      of the download (air-gapped machines). Still digest-checked.
+#   BIR_TARBALL        a local @basein/runner .tgz instead of the registry (air-gapped).
+#   BIR_NO_CLAUDE=1    do not install Claude Code.
+#   BIR_DRY_RUN=1      print every action; download, install and write nothing.
+#   HTTPS_PROXY, HTTP_PROXY, NO_PROXY, NODE_EXTRA_CA_CERTS pass through to node and npm.
+#
+# Portability: POSIX sh only (dash, and macOS's bash 3.2 as /bin/sh). Everything
+# happens inside main(), invoked on the last line, so a truncated download runs
+# nothing. It never prompts: under `curl | sh`, stdin is the script itself.
+#
+# Canonical source: scripts/install.sh in the @basein/runner repository. The API
+# serves a copy (runner-install/install.sh) with the address and version filled in.
+
+set -eu
+
+# ── output ───────────────────────────────────────────────────────────────────
+
+step() { printf '%s==> %s%s\n' "$C_STEP" "$1" "$C_OFF"; }
+note() { printf '    %s%s%s\n' "$C_NOTE" "$1" "$C_OFF"; }
+warn() { printf '    %swarning: %s%s\n' "$C_WARN" "$1" "$C_OFF" >&2; }
+die()  { printf '%serror: %s%s\n' "$C_ERR" "$1" "$C_OFF" >&2; exit 1; }
+dry()  { note "dry-run: $*"; }
+
+# ── small helpers ────────────────────────────────────────────────────────────
+
+# ver_major "v22.15.1" → 22; ver_minor → 15. Anything unparseable counts as 0.
+ver_major() {
+  _v=${1#v}; _v=${_v%%.*}
+  case "$_v" in ''|*[!0-9]*) _v=0 ;; esac
+  printf '%s\n' "$_v"
+}
+ver_minor() {
+  _v=${1#v}
+  case "$_v" in *.*) _v=${_v#*.}; _v=${_v%%.*} ;; *) _v=0 ;; esac
+  case "$_v" in ''|*[!0-9]*) _v=0 ;; esac
+  printf '%s\n' "$_v"
+}
+
+# True when a Node of this version understands --use-system-ca: 22.15+, 23.8+, 24+.
+node_has_system_ca() {
+  _maj=$(ver_major "$1"); _min=$(ver_minor "$1")
+  if [ "$_maj" -ge 24 ]; then return 0; fi
+  if [ "$_maj" -eq 22 ] && [ "$_min" -ge 15 ]; then return 0; fi
+  if [ "$_maj" -eq 23 ] && [ "$_min" -ge 8 ]; then return 0; fi
+  return 1
+}
+
+# True when a node binary lives where a version manager, a per-version package
+# directory or a per-shell shim keeps it. The SessionStart hook pins the absolute
+# path of the node it was installed with; one that moves on the next `nvm use`,
+# `brew upgrade` or shell start would leave the hook pointing at nothing.
+managed_node_path() {
+  case "$1" in
+    *fnm_multishells*|*/fnm/*|*/.fnm/*) return 0 ;;
+    */.nvm/*|*/nvm/versions/*) return 0 ;;
+    */.volta/*|*/volta/*) return 0 ;;
+    */nodenv/*|*/.nodenv/*) return 0 ;;
+    */asdf/*|*/.asdf/*) return 0 ;;
+    */mise/*|*/.mise/*) return 0 ;;
+    */scoop/*) return 0 ;;
+    */Cellar/*|*/linuxbrew/*|/snap/*) return 0 ;;
+  esac
+  return 1
+}
+
+# The two ways the script can download. Both are checked before anything
+# depends on them; the person got here through one of them.
+have_fetcher() { command -v curl >/dev/null 2>&1 || command -v wget >/dev/null 2>&1; }
+
+# fetch <url> → stdout. curl first, wget as the fallback.
+fetch() {
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL --proto '=https' "$1"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -qO- --https-only "$1"
+  else
+    die "neither curl nor wget is installed; install one and paste the line again."
+  fi
+}
+
+# sha256_of <file> → the hex digest, from whichever tool the machine has.
+sha256_of() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | awk '{ print $1 }'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$1" | awk '{ print $1 }'
+  else
+    die "neither sha256sum nor shasum is installed; the Node download cannot be verified."
+  fi
+}
+
+# is_digest <string>: exactly 64 lowercase hex characters.
+is_digest() {
+  [ ${#1} -eq 64 ] || return 1
+  case "$1" in *[!0-9a-f]*) return 1 ;; esac
+  return 0
+}
+
+# pinned_digest <archive file name> → the digest embedded for the pinned Node
+# version (nothing for any other file). Kept identical to install.ps1's table.
+pinned_digest() {
+  case "$1" in
+    node-v24.21.0-win-x64.zip)         printf '%s\n' 158f7685b44de51f6c0df1d153526cbcd3e1bc739a8dfc607721cef75de9e541 ;;
+    node-v24.21.0-win-arm64.zip)       printf '%s\n' 8779b1bde1d39f8d420e3b57aa657b39891af434d3de44a919044cec06785921 ;;
+    node-v24.21.0-darwin-arm64.tar.gz) printf '%s\n' bed7eea5325e1108f32ce5228ddd6a5f0f08a499ee42aa7442aea583702f6057 ;;
+    node-v24.21.0-darwin-x64.tar.gz)   printf '%s\n' 1462cb3b3046b815cf8ea436d3da450ec1a9f11dac7e5a46b0ada5305d7e8097 ;;
+    node-v24.21.0-linux-x64.tar.gz)    printf '%s\n' 6e1db87ef58b8819e5d5402eff1536491b18edd8eb7bee5ef7897876e88dc5ff ;;
+    node-v24.21.0-linux-arm64.tar.gz)  printf '%s\n' 724282c3b43aec998aa9527380465b45d229e021b58035f5f4f63095eabfe5d5 ;;
+  esac
+}
+
+# shasums_digest <version> <archive file name> → the digest from nodejs.org's
+# SHASUMS256.txt for that version. The file name is matched whole, against the
+# second column only; zero or several matches abort — a guess is worse than none.
+shasums_digest() {
+  _url="https://nodejs.org/dist/v$1/SHASUMS256.txt"
+  _list=$(fetch "$_url") || die "could not download $_url"
+  _hits=$(printf '%s\n' "$_list" | awk -v f="$2" '$2 == f { print $1 }')
+  _n=$(printf '%s\n' "$_hits" | awk 'NF { n++ } END { print n + 0 }')
+  case "$_n" in
+    1) printf '%s\n' "$_hits" ;;
+    0) die "$_url has no entry for $2" ;;
+    *) die "$_url has $_n entries for $2; refusing to pick one" ;;
+  esac
+}
+
+# Sets plat and arch to the names nodejs.org uses in its archive names.
+detect_platform() {
+  _os=$(uname -s 2>/dev/null || printf 'unknown')
+  _machine=$(uname -m 2>/dev/null || printf 'unknown')
+  case "$_os" in
+    Darwin)
+      plat=darwin
+      # A shell running under Rosetta reports x86_64; the machine, not the shell,
+      # decides which Node to fetch.
+      if [ "$(sysctl -n hw.optional.arm64 2>/dev/null || true)" = "1" ]; then
+        arch=arm64
+      else
+        arch=x64
+      fi
+      ;;
+    Linux)
+      plat=linux
+      case "$_machine" in
+        x86_64|amd64) arch=x64 ;;
+        aarch64|arm64) arch=arm64 ;;
+        *) die "nodejs.org has no Node build for Linux/$_machine. Install Node 20 or newer yourself and paste the line again." ;;
+      esac
+      ;;
+    *)
+      die "$_os is not supported by this script. On Windows, use the PowerShell line from the console."
+      ;;
+  esac
+}
+
+# Removes the work directory a private-Node install left behind, if any.
+cleanup() {
+  if [ -n "${work:-}" ] && [ -d "$work" ]; then rm -rf "$work"; fi
+}
+
+# ── the private Node ─────────────────────────────────────────────────────────
+#
+# Into $node_dir (versioned, so a recorder that is running keeps its files and
+# nothing is ever extracted over a binary in use). Skipped when the binary is
+# already there and answers with the right version. Download to a work
+# directory, verify, extract there, then rename into place.
+
+ensure_private_node() {
+  if [ -x "$node_dir/bin/node" ] && [ "$("$node_dir/bin/node" -v 2>/dev/null || true)" = "v$node_version" ]; then
+    note "private Node v$node_version is already in $node_dir"
+    return 0
+  fi
+
+  detect_platform
+  archive="node-v$node_version-$plat-$arch.tar.gz"
+  url="https://nodejs.org/dist/v$node_version/$archive"
+
+  if [ "$node_version" = "$NODE_PINNED" ]; then
+    expected=$(pinned_digest "$archive")
+    [ -n "$expected" ] || die "no digest is embedded for $archive"
+  else
+    note "BIR_NODE_VERSION=$node_version is not the pinned $NODE_PINNED — its digest comes from nodejs.org's SHASUMS256.txt"
+    if [ "$DRY_RUN" = 1 ]; then
+      expected="<from https://nodejs.org/dist/v$node_version/SHASUMS256.txt>"
+    else
+      expected=$(shasums_digest "$node_version" "$archive")
+      is_digest "$expected" || die "the SHASUMS256.txt entry for $archive is not a sha256 digest: $expected"
+    fi
+  fi
+
+  if [ "$DRY_RUN" = 1 ]; then
+    if [ -n "${BIR_NODE_ARCHIVE:-}" ]; then
+      dry "use $BIR_NODE_ARCHIVE instead of downloading $url"
+    else
+      dry "download $url"
+    fi
+    dry "verify sha256 = $expected"
+    dry "tar -xzf $archive --strip-components=1 into $node_dir"
+    return 0
+  fi
+
+  command -v tar >/dev/null 2>&1 || die "tar is not installed; it is needed to unpack Node."
+
+  mkdir -p "$bir_home/node"
+  work="$bir_home/node/.install-$$"
+  rm -rf "$work"
+  mkdir "$work"
+  trap cleanup EXIT
+  trap 'cleanup; exit 130' INT TERM HUP
+
+  if [ -n "${BIR_NODE_ARCHIVE:-}" ]; then
+    [ -f "$BIR_NODE_ARCHIVE" ] || die "BIR_NODE_ARCHIVE not found: $BIR_NODE_ARCHIVE"
+    note "using $BIR_NODE_ARCHIVE (BIR_NODE_ARCHIVE) instead of downloading"
+    cp "$BIR_NODE_ARCHIVE" "$work/$archive"
+  else
+    note "downloading $url"
+    have_fetcher || die "neither curl nor wget is installed; install one and paste the line again."
+    fetch "$url" > "$work/$archive" || die "download failed: $url"
+  fi
+
+  got=$(sha256_of "$work/$archive")
+  if [ "$got" != "$expected" ]; then
+    rm -f "$work/$archive"
+    die "sha256 mismatch for $archive: expected $expected, got ${got:-nothing}. The file was deleted; paste the line again."
+  fi
+  note "sha256 verified"
+
+  mkdir "$work/node"
+  tar -xzf "$work/$archive" -C "$work/node" --strip-components=1
+  [ -x "$work/node/bin/node" ] || die "$archive did not contain bin/node"
+  # Run it before it is moved into place: a build that does not start here (an
+  # older macOS, a glibc older than 2.28, musl) must say so now, not as an
+  # opaque npm failure a step later.
+  if [ "$("$work/node/bin/node" -v 2>/dev/null || true)" != "v$node_version" ]; then
+    die "the Node $node_version build does not run on this machine (it needs macOS 13.5+ or glibc 2.28+). Install Node 20 or newer yourself and paste the line again."
+  fi
+  if [ -d "$node_dir" ]; then rm -rf "$node_dir"; fi
+  mv "$work/node" "$node_dir"
+  cleanup
+  note "Node v$node_version installed in $node_dir (not on PATH; only the runner uses it)"
+}
+
+# ── the profile line ─────────────────────────────────────────────────────────
+
+# persist <file>: append the PATH line to that profile file once.
+persist() {
+  if [ -f "$1" ] && grep -qxF "$path_line" "$1"; then
+    note "already in $1"
+    return 0
+  fi
+  if [ "$DRY_RUN" = 1 ]; then
+    dry "append to $1: $path_line"
+    return 0
+  fi
+  touch "$1"
+  # A file whose last line has no newline would swallow ours.
+  if [ -s "$1" ] && [ -n "$(tail -c 1 "$1")" ]; then printf '\n' >> "$1"; fi
+  printf '%s\n' "$path_line" >> "$1"
+  note "added to $1"
+}
+
+# write_launcher <name> <script.js>: ~/.baseinstrunner/bin/<name> that execs
+# the chosen node on the installed runner's script.
+write_launcher() {
+  _launcher="$bin_dir/$1"
+  if [ "$DRY_RUN" = 1 ]; then
+    dry "write $_launcher: exec \"$node_bin\" \"$runner_dir/dist/bin/$2\" \"\$@\""
+    return 0
+  fi
+  mkdir -p "$bin_dir"
+  # The launcher carries the node flag this run used (--use-system-ca when the
+  # Node knows it), so a `bir setup` typed later trusts the same certificates.
+  printf '#!/bin/sh\nexec "%s"%s "%s/dist/bin/%s" "$@"\n' "$node_bin" "${system_ca:+ --use-system-ca}" "$runner_dir" "$2" > "$_launcher.tmp"
+  chmod +x "$_launcher.tmp"
+  mv -f "$_launcher.tmp" "$_launcher"
+  note "$_launcher"
+}
+
+# find_claude → the path of `claude`, from PATH or the native installer's
+# ~/.local/bin. Fails when there is none.
+find_claude() {
+  if command -v claude >/dev/null 2>&1; then
+    command -v claude
+    return 0
+  fi
+  if [ -x "$HOME/.local/bin/claude" ]; then
+    printf '%s\n' "$HOME/.local/bin/claude"
+    return 0
+  fi
+  return 1
+}
+
+# ── main ─────────────────────────────────────────────────────────────────────
+
+main() {
+  # 0. The token. Copied and removed from the environment before anything else
+  #    runs, so npm, the Claude Code installer and the `claude` started next
+  #    never see it. It reaches `bir setup` through that child's environment only.
+  setup_token=${BIR_SETUP_TOKEN:-}
+  unset BIR_SETUP_TOKEN
+
+  PACKAGE='@basein/runner'
+  NODE_PINNED='24.21.0'
+
+  # The API fills these two in when it serves the file. Raw from the repository
+  # they are still placeholders, which count as unset.
+  served_url='__BIR_AUTH_URL__'
+  served_version='__BIR_VERSION__'
+  case "$served_url" in __BIR_*) served_url='' ;; esac
+  case "$served_version" in __BIR_*) served_version='' ;; esac
+
+  DRY_RUN=0
+  if [ "${BIR_DRY_RUN:-}" = 1 ]; then DRY_RUN=1; fi
+
+  if [ -t 1 ]; then
+    C_STEP=$(printf '\033[36m'); C_NOTE=$(printf '\033[90m'); C_WARN=$(printf '\033[33m')
+    C_ERR=$(printf '\033[31m'); C_OFF=$(printf '\033[0m')
+  else
+    C_STEP=''; C_NOTE=''; C_WARN=''; C_ERR=''; C_OFF=''
+  fi
+
+  [ -n "${HOME:-}" ] || die "HOME is not set."
+  bir_home="$HOME/.baseinstrunner"
+  bin_dir="$bir_home/bin"
+  node_version=${BIR_NODE_VERSION:-$NODE_PINNED}
+  node_version=${node_version#v}
+  node_dir="$bir_home/node/v$node_version"
+  version=${BIR_VERSION:-${served_version:-latest}}
+  auth_url=${served_url:-${BIR_AUTH_URL:-}}
+  # shellcheck disable=SC2016
+  path_line='export PATH="$HOME/.baseinstrunner/bin:$PATH"'
+
+  # 00. The folder — before anything is downloaded. A terminal opened from the
+  #     Dock or the applications menu starts in the home directory, and that is
+  #     where a first paste tends to land.
+  step "Checking the folder"
+  # Files named relative to where the line was pasted stay valid after a cd.
+  case "${BIR_TARBALL:-}" in ''|/*) ;; *) BIR_TARBALL="$PWD/$BIR_TARBALL" ;; esac
+  case "${BIR_NODE_ARCHIVE:-}" in ''|/*) ;; *) BIR_NODE_ARCHIVE="$PWD/$BIR_NODE_ARCHIVE" ;; esac
+  if [ -n "${BIR_PROJECT:-}" ]; then
+    cd "$BIR_PROJECT" 2>/dev/null || die "BIR_PROJECT is not a directory: $BIR_PROJECT"
+  fi
+  project=$(pwd)
+  project_phys=$(pwd -P)
+  home_dir=$HOME
+  while [ "$home_dir" != "/" ] && [ "${home_dir%/}" != "$home_dir" ]; do home_dir=${home_dir%/}; done
+  home_phys=$(cd "$HOME" 2>/dev/null && pwd -P) || home_phys=$home_dir
+  what=''
+  if [ "$project" = "$home_dir" ] || [ "$project_phys" = "$home_phys" ]; then
+    what='your home folder'
+  elif [ "$project" = "/" ] || [ "$project_phys" = "/" ]; then
+    what='the root of the disk'
+  fi
+  if [ -n "$what" ]; then
+    printf '%s\n' "This is $what. Open a terminal in the project you start Claude Code in (cd there) and paste the line again." >&2
+    printf '%s\n' "(Or point the line at the project: BIR_PROJECT=/path/to/project.)" >&2
+    exit 1
+  fi
+  note "project: $project"
+  if [ "$DRY_RUN" = 1 ]; then note "dry run (BIR_DRY_RUN=1): nothing is downloaded, installed or written"; fi
+  if [ -z "$auth_url" ]; then
+    die "no service address. This is the raw script; set BIR_AUTH_URL=https://api.your-service and paste the line again (the copy the API serves has it filled in)."
+  fi
+  note "service: $auth_url"
+  if [ -n "$setup_token" ]; then
+    note "setup token: present (handed to bir setup only)"
+  else
+    note "no setup token: bir setup uses the cached sign-in, or opens the browser"
+  fi
+
+  # 1. Node.
+  step "Node"
+  node_bin=''
+  npm_cli=''
+  node_ver=''
+  if command -v node >/dev/null 2>&1; then
+    sys_ver=$(node -v 2>/dev/null || true)
+    if [ "$(ver_major "$sys_ver")" -ge 20 ]; then
+      # The shim (Volta, asdf, mise, …) is not the binary; the binary is where
+      # node_modules/npm lives and what the hook must point at.
+      sys_real=$(node -p process.execPath 2>/dev/null || true)
+      if [ -z "$sys_real" ] || [ ! -x "$sys_real" ]; then
+        note "node $sys_ver does not report its binary — using a private Node"
+      elif managed_node_path "$sys_real"; then
+        note "node $sys_ver lives in a per-version directory ($sys_real) that moves on the next upgrade or shell, and the recorder pins an absolute path — installing a private Node for it"
+      else
+        sys_root=$(cd "$(dirname "$sys_real")/.." 2>/dev/null && pwd) || sys_root=''
+        sys_npm="$sys_root/lib/node_modules/npm/bin/npm-cli.js"
+        if [ -n "$sys_root" ] && [ -f "$sys_npm" ]; then
+          node_bin=$sys_real
+          npm_cli=$sys_npm
+          node_ver=$sys_ver
+          note "using node $sys_ver at $sys_real"
+        else
+          note "node $sys_ver at $sys_real has no npm beside it — using a private Node"
+        fi
+      fi
+    else
+      note "node ${sys_ver:-(unknown version)} is older than 20 — using a private Node"
+    fi
+  else
+    note "node is not installed — using a private Node"
+  fi
+  if [ -z "$node_bin" ]; then
+    ensure_private_node
+    node_bin="$node_dir/bin/node"
+    npm_cli="$node_dir/lib/node_modules/npm/bin/npm-cli.js"
+    node_ver="v$node_version"
+  fi
+  # Node 22.15+ can trust the operating system's certificate store, which is
+  # where a company CA usually is. Older Nodes need NODE_EXTRA_CA_CERTS.
+  system_ca=''
+  if node_has_system_ca "$node_ver"; then system_ca=1; fi
+
+  # 2. The runner — one code path for both Nodes: always the private prefix,
+  #    never the machine's (root-owned after a .pkg or apt install; per-version
+  #    under nvm, Volta, asdf). Always npm-cli.js, never an `npm` shim.
+  step "Installing the runner"
+  prefix="$bir_home/npm"
+  if [ -n "${BIR_TARBALL:-}" ]; then
+    [ -f "$BIR_TARBALL" ] || die "BIR_TARBALL not found: $BIR_TARBALL"
+    spec=$BIR_TARBALL
+    note "from $BIR_TARBALL (BIR_TARBALL)"
+  else
+    spec="$PACKAGE@$version"
+    note "$spec from the npm registry"
+  fi
+  note "into $prefix (the machine's npm prefix is left alone; no sudo)"
+  runner_dir="$prefix/lib/node_modules/$PACKAGE"
+  runner_js="$runner_dir/dist/bin/bir.js"
+  if [ "$DRY_RUN" = 1 ]; then
+    dry "\"$node_bin\"${system_ca:+ --use-system-ca} \"$npm_cli\" install -g --prefix \"$prefix\" --no-fund --no-audit $spec"
+  else
+    mkdir -p "$prefix"
+    npm_log="$bir_home/npm-install.log"
+    if ! "$node_bin" ${system_ca:+--use-system-ca} "$npm_cli" install -g --prefix "$prefix" \
+        --no-fund --no-audit --loglevel=error "$spec" > "$npm_log" 2>&1; then
+      cat "$npm_log" >&2
+      if grep -qE 'CERT|ISSUER|SELF_SIGNED' "$npm_log"; then
+        printf '\n%s\n' "Your network inspects TLS. Set NODE_EXTRA_CA_CERTS to your company's CA bundle (ask IT) and run this again. Offline: BIR_TARBALL=<file.tgz> and BIR_NODE_ARCHIVE=<archive>." >&2
+      fi
+      die "npm could not install $spec (the log is in $npm_log)"
+    fi
+    rm -f "$npm_log"
+    [ -f "$runner_js" ] || die "$runner_js is missing after the install"
+    note "bir $("$node_bin" "$runner_js" --version 2>/dev/null || printf '(version unknown)') in $runner_dir"
+  fi
+
+  step "Putting bir on PATH"
+  write_launcher bir bir.js
+  write_launcher bir-hooks bir-hooks.js
+  # Which profile files a terminal reads depends on the shell and the OS: zsh
+  # reads .zprofile at login and .zshrc for every interactive shell; bash reads
+  # the first of .bash_profile / .bash_login / .profile at login (creating
+  # .bash_profile would make it stop reading .profile), and on Linux a terminal
+  # window is not a login shell, so .bashrc as well.
+  shell_name=${SHELL:-}
+  shell_name=${shell_name##*/}
+  case "$shell_name" in
+    zsh)
+      persist "$HOME/.zprofile"
+      persist "$HOME/.zshrc"
+      ;;
+    bash)
+      if [ -f "$HOME/.bash_profile" ]; then
+        persist "$HOME/.bash_profile"
+      elif [ -f "$HOME/.bash_login" ]; then
+        persist "$HOME/.bash_login"
+      else
+        persist "$HOME/.profile"
+      fi
+      if [ "$(uname -s 2>/dev/null || true)" = "Linux" ]; then persist "$HOME/.bashrc"; fi
+      ;;
+    *)
+      persist "$HOME/.profile"
+      ;;
+  esac
+  PATH="$bin_dir:$PATH"
+  export PATH
+
+  # 3. Claude Code.
+  step "Claude Code"
+  if [ "${BIR_NO_CLAUDE:-}" = 1 ]; then
+    note "skipped (BIR_NO_CLAUDE=1)"
+  elif claude_bin=$(find_claude); then
+    note "claude is installed ($claude_bin)"
+  else
+    note "installing Claude Code with its official installer — this can take a minute"
+    note "Claude Code needs a Claude subscription; it asks you to sign in the first time it starts"
+    if [ "$DRY_RUN" = 1 ]; then
+      dry "curl -fsSL https://claude.ai/install.sh | bash"
+    elif ! command -v bash >/dev/null 2>&1; then
+      warn "bash is not installed, and Claude Code's installer needs it. Install Claude Code by hand: https://docs.claude.com/en/docs/claude-code/setup"
+    elif ! have_fetcher; then
+      warn "neither curl nor wget is installed; install Claude Code by hand: https://docs.claude.com/en/docs/claude-code/setup"
+    else
+      if ! fetch https://claude.ai/install.sh | bash; then
+        warn "Claude Code's installer failed. Run it again later:  curl -fsSL https://claude.ai/install.sh | bash"
+      elif claude_bin=$(find_claude); then
+        note "claude installed ($claude_bin)"
+      else
+        warn "Claude Code did not install. Run it again later:  curl -fsSL https://claude.ai/install.sh | bash"
+      fi
+    fi
+  fi
+
+  # 4. Setup: sign in, wire the project, start the recorder. The token goes into
+  #    this child's environment and nowhere else.
+  step "Setting up the runner in $project"
+  setup_rc=0
+  if [ "$DRY_RUN" = 1 ]; then
+    token_note=''
+    if [ -n "$setup_token" ]; then token_note=' (with BIR_SETUP_TOKEN in its environment)'; fi
+    dry "\"$node_bin\"${system_ca:+ --use-system-ca} \"$runner_js\" setup --auth-url $auth_url --project \"$project\"$token_note"
+  elif [ -n "$setup_token" ]; then
+    BIR_SETUP_TOKEN=$setup_token "$node_bin" ${system_ca:+--use-system-ca} "$runner_js" setup \
+      --auth-url "$auth_url" --project "$project" || setup_rc=$?
+  else
+    "$node_bin" ${system_ca:+--use-system-ca} "$runner_js" setup \
+      --auth-url "$auth_url" --project "$project" || setup_rc=$?
+  fi
+
+  printf '\n'
+  if [ "$setup_rc" -ne 0 ]; then
+    step "bir setup exited with $setup_rc — the lines above say why. Everything it needs is installed."
+  else
+    step "Done"
+  fi
+  # A Claude Code this run installed lives in ~/.local/bin, which this terminal
+  # may not have on PATH either; the one line covers both.
+  if [ -x "$HOME/.local/bin/claude" ] && ! command -v claude >/dev/null 2>&1; then
+    # shellcheck disable=SC2016
+    path_line='export PATH="$HOME/.baseinstrunner/bin:$HOME/.local/bin:$PATH"'
+  fi
+  printf '    To use bir (and claude) in this terminal:  %s   (or open a new terminal)\n' "$path_line"
+  # shellcheck disable=SC2016
+  printf '    Check it any time:            %s\n' '"$HOME/.baseinstrunner/bin/bir" doctor'
+  exit "$setup_rc"
+}
+
+# ${1+"$@"} is "$@" on every shell, including the bash 3.2 macOS ships as
+# /bin/sh under set -u with no arguments.
+main ${1+"$@"}