From 9343715696986afbc21ec6aedbef071ae47aed16 Mon Sep 17 00:00:00 2001
From: Jeremy McClure <jeremy@jeremymcclure.com>
Date: Wed, 29 Jul 2026 11:35:43 -0400
Subject: [PATCH] zsh: print a user-facing banner when the bootstrap fires

The bootstrap silently installs tools for ~30s+ on a version bump or
first login, which looked like an unexplained hang. Now prints a
banner explaining what is happening, that it may take a minute, and
that subsequent runs are a no-op. The box is built dynamically so the
right edge stays aligned regardless of the version string length.
Also clarifies the trigger comment in zshrc.
---
 zsh/zshrc               |  5 ++++-
 zsh/zshrc-bootstrap.zsh | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/zsh/zshrc b/zsh/zshrc
index 5e106a6..8ec46a3 100644
--- a/zsh/zshrc
+++ b/zsh/zshrc
@@ -32,7 +32,10 @@ install_opencode(){
   curl -fsSL https://opencode.ai/install | bash
 }
 
-# Bootstrap: download and run once per bootstrap version
+# Bootstrap: download and run once per bootstrap version. Installs missing CLI
+# tools and oh-my-zsh/plugins across distros; prints a banner so the user knows
+# what the activity is. Re-runs only when ZSHRC_BOOTSTRAP_VERSION is bumped or
+# BOOTSTRAP=true is set.
 if [[ ! -f "$ZSHRC_BOOTSTRAP" || "$(cat "$ZSHRC_BOOTSTRAP" 2>/dev/null)" != "$ZSHRC_BOOTSTRAP_VERSION" || "$BOOTSTRAP" == "true" ]]; then
   tmp=/tmp/.zshrc_bootstrap.$$
   curl -fsSL --connect-timeout 5 --max-time 10 -o "$tmp" "$ZSHRC_BOOTSTRAP_URL" 2>/dev/null
diff --git a/zsh/zshrc-bootstrap.zsh b/zsh/zshrc-bootstrap.zsh
index c899f08..b10a86d 100644
--- a/zsh/zshrc-bootstrap.zsh
+++ b/zsh/zshrc-bootstrap.zsh
@@ -2,6 +2,40 @@ export ZSH_CONFIG=$HOME/.config/zsh
 export OHMYZSH=$ZSH_CONFIG/oh-my-zsh
 export OHMYZSH_CUSTOM=$OHMYZSH/custom
 
+# Bootstrap banner — built dynamically so the box stays aligned regardless
+# of the version string length or terminal width.
+_bootstrap_banner() {
+  local inner=61  # inner width (between the vertical bars)
+  local pad line
+  local title="Zsh bootstrap - one-time environment setup (v${ZSHRC_BOOTSTRAP_VERSION})"
+  local rule=$(printf '═%.0s' {1..$inner})
+  local mid=$(printf '─%.0s' {1..$inner})
+  # left-pad the title by 2 spaces so it doesn't hug the left bar
+  title="  $title"
+  pad=$(( inner - ${#title} ))
+  (( pad < 0 )) && pad=0
+  echo ""
+  echo "╔${rule}╗"
+  printf '║%s%*s║\n' "$title" "$pad" ""
+  echo "╠${mid}╣"
+  while IFS= read -r line; do
+    line="  $line"
+    pad=$(( inner - ${#line} ))
+    (( pad < 0 )) && pad=0
+    printf '║%s%*s║\n' "$line" "$pad" ""
+  done <<'EOF'
+This runs on first login or when the bootstrap version
+changes. It installs missing CLI tools and clones oh-my-zsh
++ plugins across distros. Network calls time out after
+~30s so an unreachable host skips silently. The first run
+may take a minute; subsequent runs are a no-op.
+EOF
+  echo "╚${rule}╝"
+  echo ""
+}
+_bootstrap_banner
+unfunction _bootstrap_banner
+
 touch ~/.hushlogin
 mkdir -p "$HOME/.local/bin"
 mkdir -p "$ZSH_CONFIG"