bootstrap.sh

#!/usr/bin/env bash
#
# bootstrap.sh - rebuild Craig's Arch toolchain on Ubuntu 26.04 (WSL)
#
# Idempotent: safe to re-run. Each section skips work already done.
#
# Usage:
#   ./bootstrap.sh              # everything
#   ./bootstrap.sh --list       # show sections without running
#   ./bootstrap.sh apt lang     # run only the named sections
#
set -euo pipefail

# ---------------------------------------------------------------------------
# Configuration
# ---------------------------------------------------------------------------

# Corporate proxy. Leave empty on a personal machine.
# Example: PROXY="http://127.0.0.1:3128"
PROXY="${PROXY:-}"

# Corporate root CA to trust, if any. Path to a .crt on the Windows side or
# already inside WSL. Leave empty to skip.
CORP_CA="${CORP_CA:-}"

# Third-party apt repos (Microsoft, HashiCorp, Puppet) publish per-suite.
# 26.04 is "resolute"; those vendors usually lag a new LTS by a few months.
# Set to "auto" once they catch up.
REPO_SUITE="${REPO_SUITE:-noble}"

# Install Homebrew and its packages.
INSTALL_BREW="${INSTALL_BREW:-true}"

# From `brew leaves --installed-on-request` on the Arch box.
# gcc is omitted: build-essential covers it and brew's gcc is a large,
# slow install that mostly exists to bootstrap other formulae.
BREW_PKGS=(
  cloudflared
  conftest
  gh
  graphviz
  just
  nvm
  poppler
  starship
  terraform-docs
  trivy
)

SECRETS_FILE="$HOME/.config/shell/secrets.env"
LOCAL_BIN="$HOME/.local/bin"

# Shared developer virtualenv at ~/.venvs/developer
VENV_PYTHON="${VENV_PYTHON:-3.12}"
VENV_PKGS=(
  ansible-core
  ansible-lint
  pre-commit
  pyyaml
  requests
  azure-identity
  azure-mgmt-resource
  msgraph-sdk
  pandas
  rich
)

# PowerShell modules, installed at user scope from PSGallery.
# Az and Microsoft.Graph are meta-modules that pull in dozens of sub-modules
# each, so a cold install of either takes several minutes. That is expected
# and is not a hang.
# LibreDevOpsHelpers is Craig's own module. If it does not resolve from the
# public gallery, register the feed with PSGALLERY_TOKEN before running this.
PS_MODULES=(
  Az
  Microsoft.Graph
  Pester
  LibreDevOpsHelpers
)

# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------

log()  { printf '\n\033[1;34m==>\033[0m %s\n' "$*"; }
warn() { printf '\033[1;33m[warn]\033[0m %s\n' "$*" >&2; }
skip() { printf '     \033[2mskip: %s\033[0m\n' "$*"; }

have() { command -v "$1" >/dev/null 2>&1; }

ARCH_DEB="$(dpkg --print-architecture)"

# Several upstreams name their release assets with the GNU architecture rather
# than the Debian one, so keep both spellings to hand.
case "$ARCH_DEB" in
  amd64) ARCH_GNU="x86_64" ;;
  arm64) ARCH_GNU="aarch64" ;;
  *)     ARCH_GNU="$(uname -m)" ;;
esac

. /etc/os-release
SUITE="$REPO_SUITE"
[ "$SUITE" = "auto" ] && SUITE="$UBUNTU_CODENAME"

# Download a URL to stdout, honouring proxy.
fetch() { curl -fsSL --retry 3 "$@"; }

# Add a deb822 apt source with a dearmoured key.
# add_repo <name> <key-url> <repo-url> [suite] [components]
add_repo() {
  local name="$1" keyurl="$2" repourl="$3" suite="${4:-$SUITE}" comps="${5:-main}"
  local keyring="/etc/apt/keyrings/${name}.gpg"
  local srcfile="/etc/apt/sources.list.d/${name}.sources"

  if [ -f "$srcfile" ] && [ -f "$keyring" ]; then
    skip "apt repo $name"
    return 0
  fi

  sudo install -d -m 0755 /etc/apt/keyrings

  local tmpkey; tmpkey="$(mktemp)"
  if ! fetch -o "$tmpkey" "$keyurl"; then
    rm -f "$tmpkey"
    warn "could not fetch signing key for '${name}': ${keyurl}"
    warn "skipping this repo; packages from it will not install"
    return 0
  fi

  # gpg --dearmor passes binary keys through unchanged, so this handles
  # both .asc (armoured) and .gpg (binary) sources.
  if ! sudo gpg --dearmor --yes -o "$keyring" < "$tmpkey"; then
    rm -f "$tmpkey"
    warn "signing key for '${name}' was not valid OpenPGP data: ${keyurl}"
    return 0
  fi
  rm -f "$tmpkey"
  sudo chmod 0644 "$keyring"

  sudo tee "$srcfile" >/dev/null <<EOF
Types: deb
URIs: ${repourl}
Suites: ${suite}
Components: ${comps}
Architectures: ${ARCH_DEB}
Signed-By: ${keyring}
EOF
  APT_DIRTY=1
}

APT_DIRTY=0
apt_refresh() {
  if [ "$APT_DIRTY" = "1" ]; then
    sudo apt-get update -qq
    APT_DIRTY=0
  fi
}

# Install a .deb from a URL if the named binary is missing.
# deb_install <binary> <url>
# A download or install that fails here must warn and let the run continue.
# One unavailable vendor asset should leave a degraded machine, not an aborted
# provisioner that has skipped everything after it.
deb_install() {
  local bin="$1" url="$2" tmp
  if have "$bin"; then skip "$bin already installed"; return 0; fi
  tmp="$(mktemp -d)"
  if ! fetch -o "$tmp/pkg.deb" "$url"; then
    rm -rf "$tmp"
    warn "could not download ${bin}: ${url}"
    return 0
  fi
  sudo apt-get install -y -qq "$tmp/pkg.deb" \
    || warn "could not install ${bin} from ${url}"
  rm -rf "$tmp"
}

# Extract a single binary from a tarball into ~/.local/bin.
# tar_install <binary> <url> <path-inside-archive>
tar_install() {
  local bin="$1" url="$2" inner="$3" tmp
  if have "$bin"; then skip "$bin already installed"; return 0; fi
  tmp="$(mktemp -d)"
  if ! fetch -o "$tmp/a.tgz" "$url"; then
    rm -rf "$tmp"
    warn "could not download ${bin}: ${url}"
    return 0
  fi
  if ! tar -xzf "$tmp/a.tgz" -C "$tmp"; then
    warn "could not unpack the archive for ${bin}: ${url}"
  elif ! install -Dm755 "$tmp/$inner" "$LOCAL_BIN/$bin"; then
    warn "the archive for ${bin} did not contain '${inner}'"
  fi
  rm -rf "$tmp"
}

# Resolve the latest release tag for a GitHub repo.
#
# Read from the /releases/latest redirect rather than the API, because the
# unauthenticated API allows 60 requests an hour per IP and this script makes
# several. The API stays as a fallback.
#
# Returns 1 and warns when the tag cannot be resolved. Callers must use
# "|| true" so that set -e does not abort the run over it.
gh_latest() {
  local tag url
  url="$(fetch -I -o /dev/null -w '%{url_effective}' \
    "https://github.com/$1/releases/latest" 2>/dev/null)" || true
  case "$url" in
    */releases/tag/*) tag="${url##*/tag/}" ;;
    *)                tag="" ;;
  esac

  if [ -z "$tag" ]; then
    tag="$(fetch "https://api.github.com/repos/$1/releases/latest" 2>/dev/null \
      | grep -m1 '"tag_name"' | cut -d'"' -f4)" || true
  fi

  if [ -z "$tag" ]; then
    warn "could not resolve the latest release of $1 (no releases published, rate limited, or no network)"
    return 1
  fi
  printf '%s\n' "$tag"
}

# Resolve the latest release tag for a GitLab project.
#
# glab is developed on GitLab. Its GitHub repo is a read-only mirror that
# publishes no GitHub releases at all, so gh_latest can never resolve it and
# the download URL came out malformed every time.
# gl_latest <project path, for example gitlab-org/cli>
gl_latest() {
  local tag url
  url="$(fetch -I -o /dev/null -w '%{url_effective}' \
    "https://gitlab.com/$1/-/releases/permalink/latest" 2>/dev/null)" || true
  case "$url" in
    */-/releases/*) tag="${url##*/releases/}" ;;
    *)              tag="" ;;
  esac

  if [ -z "$tag" ]; then
    warn "could not resolve the latest release of gitlab.com/$1"
    return 1
  fi
  printf '%s\n' "$tag"
}

# ---------------------------------------------------------------------------
# Sections
# ---------------------------------------------------------------------------

section_proxy() {
  log "Proxy and CA trust"

  if [ -z "$PROXY" ]; then
    skip "no PROXY set"
  else
    sudo tee /etc/apt/apt.conf.d/00proxy >/dev/null <<EOF
Acquire::http::Proxy "${PROXY}";
Acquire::https::Proxy "${PROXY}";
EOF
    # /etc/environment is read by non-shell consumers too (systemd, VS Code server)
    local noproxy="localhost,127.0.0.1,::1,.local,.internal"
    sudo sed -i '/^\(http\|https\|no\|HTTP\|HTTPS\|NO\)_proxy=/d;/^\(HTTP\|HTTPS\|NO\)_PROXY=/d' /etc/environment
    sudo tee -a /etc/environment >/dev/null <<EOF
http_proxy=${PROXY}
https_proxy=${PROXY}
HTTP_PROXY=${PROXY}
HTTPS_PROXY=${PROXY}
no_proxy=${noproxy}
NO_PROXY=${noproxy}
EOF
    export http_proxy="$PROXY" https_proxy="$PROXY"
    export HTTP_PROXY="$PROXY" HTTPS_PROXY="$PROXY"
    export no_proxy="$noproxy" NO_PROXY="$noproxy"
  fi

  if [ -z "$CORP_CA" ]; then
    skip "no CORP_CA set"
  elif [ ! -f "$CORP_CA" ]; then
    warn "CORP_CA set to '$CORP_CA' but that file does not exist"
  else
    sudo apt-get install -y -qq ca-certificates
    sudo install -Dm644 "$CORP_CA" \
      "/usr/local/share/ca-certificates/$(basename "${CORP_CA%.*}").crt"
    sudo update-ca-certificates
  fi
}

section_apt() {
  log "Base packages from Ubuntu archive"

  sudo apt-get update -qq
  sudo apt-get install -y -qq \
    build-essential pkg-config ca-certificates curl wget gnupg lsb-release \
    git git-lfs openssh-client gnupg2 \
    7zip zip unzip xz-utils dos2unix \
    bind9-dnsutils iputils-ping net-tools traceroute \
    htop ncdu tree less lsof strace \
    jq nano neovim \
    graphviz poppler-utils \
    man-db manpages manpages-dev \
    podman podman-compose slirp4netns fuse-overlayfs uidmap \
    python3 python3-venv python3-pip \
    fonts-crosextra-carlito fonts-dejavu fonts-liberation \
    pandoc \
    texlive-latex-base texlive-latex-recommended texlive-latex-extra \
    texlive-fonts-recommended texlive-fonts-extra texlive-xetex

  git lfs install --skip-repo >/dev/null
}

section_repos() {
  log "Third-party apt repositories (suite: ${SUITE})"

  # Microsoft: azure-cli, powershell, dotnet
  add_repo microsoft \
    "https://packages.microsoft.com/keys/microsoft.asc" \
    "https://packages.microsoft.com/ubuntu/${SUITE//noble/24.04}/prod" \
    "$SUITE" "main"

  # Azure CLI has its own feed and is not carried in the prod one, at least
  # not for noble. Its absence there is what made the single apt-get call
  # below fail, which silently took powershell and gh down with it.
  add_repo azure-cli \
    "https://packages.microsoft.com/keys/microsoft.asc" \
    "https://packages.microsoft.com/repos/azure-cli" \
    "$SUITE" "main"

  # HashiCorp: kept for packer/vault/consul if you want them later.
  add_repo hashicorp \
    "https://apt.releases.hashicorp.com/gpg" \
    "https://apt.releases.hashicorp.com" \
    "$SUITE" "main"

  # GitHub CLI. Note the keyring is .gpg (binary); there is no .asc variant.
  add_repo githubcli \
    "https://cli.github.com/packages/githubcli-archive-keyring.gpg" \
    "https://cli.github.com/packages" \
    "stable" "main"

  # Puppet (for pdk). Their signing key filename carries a rotation date that
  # changes periodically, so use the release deb, which configures both the
  # repo and the correct key for us.
  if [ ! -f /etc/apt/sources.list.d/puppet-tools.list ] && ! have pdk; then
    local ptmp; ptmp="$(mktemp -d)"
    if fetch -o "$ptmp/puppet.deb" \
        "https://apt.puppet.com/puppet-tools-release-${SUITE}.deb"; then
      sudo apt-get install -y -qq "$ptmp/puppet.deb" && APT_DIRTY=1
    else
      warn "no puppet-tools release deb for ${SUITE}; pdk will be skipped"
    fi
    rm -rf "$ptmp"
  else
    skip "puppet repo"
  fi

  # Cloudflare (cloudflared)
  add_repo cloudflare \
    "https://pkg.cloudflare.com/cloudflare-main.gpg" \
    "https://pkg.cloudflare.com/cloudflared" \
    "$SUITE" "main"

  # Aqua Security (trivy)
  add_repo trivy \
    "https://aquasecurity.github.io/trivy-repo/deb/public.key" \
    "https://aquasecurity.github.io/trivy-repo/deb" \
    "$SUITE" "main"

  apt_refresh

  log "Vendor packages"

  # One package per call, deliberately. A single apt-get naming several
  # packages installs none of them if any one is unavailable, so an azure-cli
  # that the vendor has not published for this suite used to take powershell
  # and gh with it, and the warning blamed all three.
  local p
  for p in azure-cli powershell gh cloudflared trivy pdk; do
    sudo apt-get install -y -qq "$p" \
      || warn "${p} is unavailable for ${SUITE}; check that the vendor publishes that suite"
  done

  # Microsoft carries one SDK series per suite and retires the older ones, so
  # take the newest that resolves rather than pinning a version that ages out.
  local d
  for d in dotnet-sdk-10.0 dotnet-sdk-9.0 dotnet-sdk-8.0; do
    if sudo apt-get install -y -qq "$d" 2>/dev/null; then
      break
    fi
  done
  have dotnet || warn "no dotnet SDK installed"
}

section_bins() {
  log "Standalone binaries"
  mkdir -p "$LOCAL_BIN"

  local t g c td j sc tmp

  # yq (mikefarah) - note Ubuntu's "yq" package is the wrong project
  if ! have yq; then
    if fetch -o "$LOCAL_BIN/yq" \
        "https://github.com/mikefarah/yq/releases/latest/download/yq_linux_${ARCH_DEB}"; then
      chmod 0755 "$LOCAL_BIN/yq"
    else
      warn "could not download yq"
    fi
  else skip "yq"; fi

  # tenv - terraform/tofu/terragrunt/atmos version manager
  if ! have tenv; then
    t="$(gh_latest tofuutils/tenv || true)"
    if [ -n "$t" ]; then
      deb_install tenv \
        "https://github.com/tofuutils/tenv/releases/download/${t}/tenv_${t}_${ARCH_DEB}.deb"
    fi
  else skip "tenv"; fi

  # glab
  if ! have glab; then
    g="$(gl_latest gitlab-org/cli || true)"
    if [ -n "$g" ]; then
      deb_install glab \
        "https://gitlab.com/gitlab-org/cli/-/releases/${g}/downloads/glab_${g#v}_linux_${ARCH_DEB}.deb"
    fi
  else skip "glab"; fi

  # conftest (OPA policy testing)
  if ! have conftest; then
    c="$(gh_latest open-policy-agent/conftest || true)"; c="${c#v}"
    if [ -n "$c" ]; then
      tar_install conftest \
        "https://github.com/open-policy-agent/conftest/releases/download/v${c}/conftest_${c}_Linux_${ARCH_GNU}.tar.gz" \
        "conftest"
    fi
  else skip "conftest"; fi

  # terraform-docs
  if ! have terraform-docs; then
    td="$(gh_latest terraform-docs/terraform-docs || true)"
    if [ -n "$td" ]; then
      tar_install terraform-docs \
        "https://github.com/terraform-docs/terraform-docs/releases/download/${td}/terraform-docs-${td}-linux-${ARCH_DEB}.tar.gz" \
        "terraform-docs"
    fi
  else skip "terraform-docs"; fi

  # just - try the archive first, fall back to the release tarball
  if ! have just; then
    if ! sudo apt-get install -y -qq just 2>/dev/null; then
      j="$(gh_latest casey/just || true)"
      if [ -n "$j" ]; then
        tar_install just \
          "https://github.com/casey/just/releases/download/${j}/just-${j}-${ARCH_GNU}-unknown-linux-musl.tar.gz" \
          "just"
      fi
    fi
  else skip "just"; fi

  # Install the linter itself. The bash in this repo has to stay clean at
  # -S warning, so it belongs on the machine and not only in CI. Static
  # binary, so no sudo is needed, but the asset is .tar.xz rather than the
  # .tar.gz that tar_install expects, hence the longhand.
  # Note: a comment must not begin with the word shellcheck, because that is
  # the directive prefix and the parser rejects it.
  if ! have shellcheck; then
    sc="$(gh_latest koalaman/shellcheck || true)"
    if [ -n "$sc" ]; then
      tmp="$(mktemp -d)"
      if ! fetch -o "$tmp/sc.tar.xz" \
          "https://github.com/koalaman/shellcheck/releases/download/${sc}/shellcheck-${sc}.linux.${ARCH_GNU}.tar.xz"; then
        warn "could not download shellcheck ${sc}"
      elif ! tar -xJf "$tmp/sc.tar.xz" -C "$tmp"; then
        warn "could not unpack shellcheck (is xz-utils installed?)"
      else
        install -Dm755 "$tmp/shellcheck-${sc}/shellcheck" "$LOCAL_BIN/shellcheck" \
          || warn "unexpected layout inside the shellcheck archive"
      fi
      rm -rf "$tmp"
    fi
  else skip "shellcheck"; fi

  # keybase
  deb_install keybase \
    "https://prerelease.keybase.io/keybase_${ARCH_DEB}.deb"

  # starship prompt.
  #
  # Install into ~/.local/bin rather than the installer's default of
  # /usr/local/bin. To write there the installer calls "sudo -v" to
  # pre-validate, and sudo -v asks for a password even under NOPASSWD:ALL
  # because it matches no specific command. With no TTY that blocks forever
  # rather than failing, which hangs the whole run.
  if ! have starship; then
    fetch https://starship.rs/install.sh \
      | sh -s -- --yes --bin-dir "$LOCAL_BIN" \
      || warn "starship install failed"
  else skip "starship"; fi

  # uv (brings uvx, and manages python + tool installs)
  if ! have uv; then
    fetch https://astral.sh/uv/install.sh | sh || warn "uv install failed"
  else skip "uv"; fi
}

section_lang() {
  log "Language toolchains"

  local n

  # goenv
  if [ ! -d "$HOME/.goenv" ]; then
    git clone --depth 1 https://github.com/go-nv/goenv.git "$HOME/.goenv" \
      || warn "goenv clone failed"
  else skip "goenv"; fi

  # nvm (was via brew; use upstream installer instead)
  if [ ! -d "$HOME/.nvm" ]; then
    n="$(gh_latest nvm-sh/nvm || true)"
    if [ -n "$n" ]; then
      fetch "https://raw.githubusercontent.com/nvm-sh/nvm/${n}/install.sh" \
        | PROFILE=/dev/null bash || warn "nvm install failed"
    fi
  else skip "nvm"; fi

  # sdkman
  if [ ! -d "$HOME/.sdkman" ]; then
    fetch https://get.sdkman.io | bash || warn "sdkman install failed"
  else skip "sdkman"; fi

  # Global CLI tools via uv, replacing pipx-managed installs.
  # Project-scoped Python libraries go in ~/.venvs/developer instead.
  if have uv; then
    export PATH="$HOME/.local/bin:$PATH"
    uv python install "$VENV_PYTHON" 3.13 || true
    uv tool install --quiet pre-commit || warn "pre-commit install failed"
  fi
}

section_venv() {
  log "Developer virtualenv (~/.venvs/developer)"

  if ! have uv; then
    warn "uv not on PATH; run the 'bins' section first"
    return 0
  fi

  local venv="$HOME/.venvs/developer"
  mkdir -p "$HOME/.venvs"

  if [ ! -d "$venv" ]; then
    uv venv --python "$VENV_PYTHON" "$venv"
  else
    skip "venv exists"
  fi

  VIRTUAL_ENV="$venv" uv pip install --quiet --upgrade "${VENV_PKGS[@]}" \
    || warn "some venv packages failed to install"

  local marker="# developer venv"
  if ! grep -qF "$marker" "$HOME/.bashrc" 2>/dev/null; then
    cat >> "$HOME/.bashrc" <<'EOF'

# developer venv
dev() { . "$HOME/.venvs/developer/bin/activate"; }
EOF
  fi
}

section_brew() {
  if [ "$INSTALL_BREW" != "true" ]; then
    log "Homebrew"; skip "INSTALL_BREW is not true"
    return 0
  fi

  log "Homebrew"

  # Homebrew's own documented prerequisites on Linux
  sudo apt-get install -y -qq build-essential procps curl file git

  if [ ! -x /home/linuxbrew/.linuxbrew/bin/brew ]; then
    NONINTERACTIVE=1 bash -c \
      "$(fetch https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  else
    skip "brew already installed"
  fi

  if [ ! -x /home/linuxbrew/.linuxbrew/bin/brew ]; then
    warn "brew install did not produce a usable binary; skipping formulae"
    return 0
  fi

  eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

  # Brew builds from source when no bottle matches, which needs the proxy
  # visible to the compiler toolchain too.
  if [ -n "$PROXY" ]; then
    export ALL_PROXY="$PROXY"
    export HOMEBREW_NO_AUTO_UPDATE=1
  fi

  local todo=()
  local p
  for p in "${BREW_PKGS[@]}"; do
    if brew list --formula "$p" >/dev/null 2>&1; then
      skip "brew: $p"
    else
      todo+=("$p")
    fi
  done

  if [ "${#todo[@]}" -gt 0 ]; then
    log "brew install: ${todo[*]}"
    brew install "${todo[@]}" || warn "one or more formulae failed; re-run this section"
  fi

  brew cleanup --prune=all >/dev/null 2>&1 || true
}

# A pwsh resolving under /mnt is the Windows one that WSL appends to PATH.
# It is not part of a provisioned Linux toolchain, so neither install into it
# nor count it as present.
linux_pwsh() {
  local p
  p="$(command -v pwsh 2>/dev/null || true)"
  case "$p" in
    ""|/mnt/*) return 1 ;;
    *)         printf '%s\n' "$p" ;;
  esac
}

# ps_module_present <module-name>
ps_module_present() {
  pwsh -NoProfile -NonInteractive -Command \
    "if (Get-Module -ListAvailable -Name '$1') { exit 0 } else { exit 1 }" \
    >/dev/null 2>&1
}

section_psmodules() {
  log "PowerShell modules (user scope)"

  if ! linux_pwsh >/dev/null; then
    warn "no Linux pwsh on PATH; run the 'repos' section first"
    return 0
  fi

  # Trust the gallery once so that Install-Module does not stop on the
  # untrusted repository prompt in a non-interactive shell.
  pwsh -NoProfile -NonInteractive -Command \
    "Set-PSRepository -Name PSGallery -InstallationPolicy Trusted -ErrorAction SilentlyContinue" \
    >/dev/null 2>&1 || true

  local m
  for m in "${PS_MODULES[@]}"; do
    if ps_module_present "$m"; then
      skip "pwsh module ${m}"
      continue
    fi

    log "installing ${m} (Az and Microsoft.Graph take several minutes)"
    if ! pwsh -NoProfile -NonInteractive -Command \
        "Install-Module -Name '${m}' -Scope CurrentUser -Repository PSGallery -Force -AllowClobber -ErrorAction Stop"; then
      if [ "$m" = "LibreDevOpsHelpers" ]; then
        warn "could not install ${m}; if it is not on the public gallery, register that feed with PSGALLERY_TOKEN first"
      else
        warn "could not install PowerShell module ${m}"
      fi
    fi
  done
}

section_shell() {
  log "Shell configuration"

  mkdir -p "$(dirname "$SECRETS_FILE")"
  if [ ! -f "$SECRETS_FILE" ]; then
    cat > "$SECRETS_FILE" <<'EOF'
# Secrets and per-machine config. Never commit this file.
# Populate with freshly rotated values.

# export ARM_TENANT_ID=""
# export ARM_SUBSCRIPTION_ID=""
# export CLOUDFLARE_ACCOUNT_ID=""
# export CLOUDFLARE_ZONE_ID=""
# export CLOUDFLARE_API_TOKEN=""
# export PUPPET_FORGE_API_KEY=""
# export PSGALLERY_TOKEN=""
# export GITHUB_TOKEN=""
# export TF_VAR_github_token="$GITHUB_TOKEN"
# export SNOW_URL=""
# export SNOW_USERNAME=""
# export SNOW_PASSWORD=""
# export TF_VAR_SNOW_OAUTH_CLIENT_ID=""
# export TF_VAR_SNOW_OAUTH_CLIENT_SECRET=""
# export TF_VAR_SNOW_OAUTH_USERNAME=""
# export TF_VAR_SNOW_OAUTH_PASSWORD=""
EOF
    chmod 0600 "$SECRETS_FILE"
  else
    chmod 0600 "$SECRETS_FILE"
    skip "secrets.env exists"
  fi

  # Rewrite the managed block on every run rather than skipping when it is
  # already there. A block that can only ever be appended can never be
  # corrected on a machine that has already been provisioned, which quietly
  # made every later fix to it a manual edit.
  if grep -qF "# >>> bootstrap managed >>>" "$HOME/.bashrc" 2>/dev/null; then
    sed -i '/^# >>> bootstrap managed >>>$/,/^# <<< bootstrap managed <<<$/d' \
      "$HOME/.bashrc"
    # Drop the blank lines that deletion leaves at the end, so repeated runs
    # do not accumulate them.
    sed -i -e :a -e '/^$/{$d;N;ba' -e '}' "$HOME/.bashrc"
  fi

  cat >> "$HOME/.bashrc" <<'EOF'

# >>> bootstrap managed >>>
export LANG=en_GB.UTF-8
alias ls='ls --color=auto'
alias grep='grep --color=auto'

# PATH precedence, lowest to highest.
# Brew goes in first so that anything installed via apt, uv or a direct
# binary drop takes priority over a brew formula of the same name.
[ -x /home/linuxbrew/.linuxbrew/bin/brew ] && \
  eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

# brew shellenv prepends its own bin, which lands it ahead of /usr/bin and
# lets a formula shadow the apt package of the same name: gh, just, trivy,
# cloudflared, and graphviz's dot and poppler's pdftotext. Put the system
# paths back in front so the precedence above is what actually happens.
# Duplicate PATH entries are harmless, because the first match wins.
export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PATH"

export GOENV_ROOT="$HOME/.goenv"
export PATH="$GOENV_ROOT/bin:$PATH"
command -v goenv >/dev/null && eval "$(goenv init -)"
export PATH="$HOME/go/bin:$PATH"

export PATH="$HOME/.local/bin:$PATH"

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"

export SDKMAN_DIR="$HOME/.sdkman"
[ -s "$SDKMAN_DIR/bin/sdkman-init.sh" ] && . "$SDKMAN_DIR/bin/sdkman-init.sh"

# GPG needs a TTY for pinentry when signing commits
export GPG_TTY="$(tty)"

# Secrets live outside version control
[ -f "$HOME/.config/shell/secrets.env" ] && . "$HOME/.config/shell/secrets.env"

# Non-secret Azure defaults
export ARM_STORAGE_USE_AZUREAD="true"
export ARM_USE_CLI="true"

command -v starship >/dev/null && eval "$(starship init bash)"
# <<< bootstrap managed <<<
EOF
}

section_git() {
  log "Git configuration"

  # Resolve to a stable absolute path. Prefer the distro package over brew,
  # so the config survives a `brew cleanup` or a brew reinstall. This is
  # deliberately not `command -v`, which would depend on which sections of
  # this script have already run and modified PATH.
  local gh_path glab_path
  for c in /usr/bin/gh /home/linuxbrew/.linuxbrew/bin/gh; do
    [ -x "$c" ] && { gh_path="$c"; break; }
  done
  gh_path="${gh_path:-$(command -v gh || echo /usr/bin/gh)}"

  for c in /usr/bin/glab /home/linuxbrew/.linuxbrew/bin/glab; do
    [ -x "$c" ] && { glab_path="$c"; break; }
  done
  glab_path="${glab_path:-$(command -v glab || echo /usr/bin/glab)}"

  git config --global user.name  "Craig Thacker"
  git config --global user.email "craigthackerx@gmail.com"
  git config --global user.signingkey "82D2F9D5BA2AE757"
  git config --global commit.gpgsign true
  git config --global gpg.program gpg

  git config --global core.editor nano
  git config --global core.longpaths true
  git config --global credential.useHttpPath true
  git config --global credential.azreposCredentialType oauth

  git config --global alias.a "add --all"
  git config --global alias.c "commit"
  git config --global alias.p "push"

  # Rebuild credential helpers against real paths, not brew's
  for host in "https://github.com" "https://gist.github.com"; do
    git config --global --unset-all "credential.${host}.helper" 2>/dev/null || true
    git config --global --add "credential.${host}.helper" ""
    git config --global --add "credential.${host}.helper" "!${gh_path} auth git-credential"
  done
  git config --global --unset-all "credential.https://gitlab.com.helper" 2>/dev/null || true
  git config --global --add "credential.https://gitlab.com.helper" ""
  git config --global --add "credential.https://gitlab.com.helper" "!${glab_path} auth git-credential"

  git config --global filter.lfs.process "git-lfs filter-process"
  git config --global filter.lfs.required true
  git config --global filter.lfs.clean "git-lfs clean -- %f"
  git config --global filter.lfs.smudge "git-lfs smudge -- %f"
}

section_ssh() {
  log "SSH directory permissions"
  mkdir -p "$HOME/.ssh"
  chmod 0700 "$HOME/.ssh"
  [ -f "$HOME/.ssh/id_ed25519" ]     && chmod 0600 "$HOME/.ssh/id_ed25519"
  [ -f "$HOME/.ssh/id_ed25519.pub" ] && chmod 0644 "$HOME/.ssh/id_ed25519.pub"
  [ -f "$HOME/.ssh/known_hosts" ]    && chmod 0644 "$HOME/.ssh/known_hosts"

  if [ ! -f "$HOME/.ssh/config" ]; then
    cat > "$HOME/.ssh/config" <<'EOF'
Host *
    AddKeysToAgent yes
    IdentityFile ~/.ssh/id_ed25519
    ServerAliveInterval 60

Host github.com
    User git
    IdentitiesOnly yes

Host gitlab.com
    User git
    IdentitiesOnly yes
EOF
    chmod 0600 "$HOME/.ssh/config"
  else
    chmod 0600 "$HOME/.ssh/config"
    skip "ssh config exists"
  fi

  if [ ! -f "$HOME/.ssh/id_ed25519" ]; then
    warn "no private key at ~/.ssh/id_ed25519 - copy it from the Arch box"
  fi
}

section_verify() {
  log "Verification"
  local missing=0
  # Two traps here, both of which made this check report the wrong answer.
  #
  # WSL appends the Windows PATH to the Linux PATH, so a tool installed only on
  # the Windows side still resolves. az and pwsh are the usual culprits, and
  # both are mandatory, so a Windows az would have passed this check on a box
  # with no Linux az at all. A /mnt/ resolution is not a provisioned Linux
  # toolchain, so count it as missing and say why.
  #
  # graphviz is checked as "dot" because the package ships dot, neato and
  # friends but never a binary called graphviz, so the package name could never
  # resolve and always reported missing.
  local resolved
  for b in git gh glab jq yq tenv az pwsh podman nvim htop tree pandoc \
           uv starship keybase dos2unix \
           cloudflared conftest just trivy terraform-docs dot \
           pdftotext shellcheck; do
    resolved="$(command -v "$b" 2>/dev/null || true)"
    case "$resolved" in
      "")
        printf '  \033[0;31mmiss\033[0m %s\n' "$b"
        missing=1
        ;;
      /mnt/*)
        printf '  \033[0;31mmiss\033[0m %-12s (Windows side only: %s)\n' "$b" "$resolved"
        missing=1
        ;;
      *)
        printf '  \033[0;32mok\033[0m   %-12s %s\n' "$b" "$resolved"
        ;;
    esac
  done

  if [ -x "$HOME/.venvs/developer/bin/python" ]; then
    printf '  \033[0;32mok\033[0m   venv         %s\n' \
      "$("$HOME/.venvs/developer/bin/python" -V 2>&1)"
  else
    printf '  \033[0;31mmiss\033[0m ~/.venvs/developer\n'; missing=1
  fi

  if [ -x /home/linuxbrew/.linuxbrew/bin/brew ]; then
    printf '  \033[0;32mok\033[0m   brew         %s formulae\n' \
      "$(/home/linuxbrew/.linuxbrew/bin/brew list --formula 2>/dev/null | wc -l)"
    log "Binaries present in more than one place (first listed wins)"
    for b in gh starship just conftest trivy terraform-docs cloudflared; do
      local n; n="$(type -a "$b" 2>/dev/null | wc -l)"
      [ "$n" -gt 1 ] && printf '  %-14s %s\n' "$b" \
        "$(type -a "$b" 2>/dev/null | awk '{print $NF}' | paste -sd' ')"
    done
  fi

  if gpg --list-secret-keys 82D2F9D5BA2AE757 >/dev/null 2>&1; then
    printf '  \033[0;32mok\033[0m   gpg signing key present\n'
  else
    printf '  \033[0;31mmiss\033[0m gpg signing key 82D2F9D5BA2AE757 not imported\n'
    missing=1
  fi

  # pwsh and az are mandatory, and so are these modules, so a machine without
  # them is not provisioned. Only ever check against a Linux pwsh.
  if linux_pwsh >/dev/null; then
    local m
    for m in "${PS_MODULES[@]}"; do
      if ps_module_present "$m"; then
        printf '  \033[0;32mok\033[0m   psmodule     %s\n' "$m"
      else
        printf '  \033[0;31mmiss\033[0m psmodule     %s\n' "$m"
        missing=1
      fi
    done
  else
    printf '  \033[0;31mmiss\033[0m psmodules    (no Linux pwsh to check against)\n'
    missing=1
  fi

  if [ "$missing" = "0" ]; then
    log "All checks passed."
    return 0
  fi

  warn "Some items missing. Re-run, or install those individually."
  return 1
}

# ---------------------------------------------------------------------------
# Driver
# ---------------------------------------------------------------------------

SECTIONS=(proxy apt repos bins lang venv brew psmodules shell git ssh verify)

if [ "${1:-}" = "--list" ]; then
  printf '%s\n' "${SECTIONS[@]}"
  exit 0
fi

if [ "$#" -gt 0 ]; then
  SECTIONS=("$@")
fi

# verify reports rather than provisions, so let its result set the exit status
# without aborting whatever was queued behind it. Every other section keeps the
# set -e behaviour, where a genuine failure stops the run.
VERIFY_RC=0

for s in "${SECTIONS[@]}"; do
  if ! declare -F "section_${s}" >/dev/null; then
    warn "unknown section: ${s}"
    continue
  fi

  if [ "$s" = "verify" ]; then
    "section_${s}" || VERIFY_RC=1
  else
    "section_${s}"
  fi
done

log "Done. Open a new shell, or run: source ~/.bashrc"
exit "$VERIFY_RC"