bloby-bot 0.70.12 → 0.71.0

package/scripts/install

@@ -7,6 +7,23 @@ set -e
 # Downloads Node.js + Bloby into ~/.bloby — no system dependencies needed.
 # ─────────────────────────────────────────────────────────────────────────────
 
+# Repair $HOME before deriving any install path. Under `sudo`, cron, CI, or a
+# minimal shell, $HOME can be empty or "/" — without this we'd install into the
+# wrong place (or /). Colors aren't defined yet, so this early error is plain.
+if [ -z "${HOME:-}" ] || [ ! -d "${HOME:-}" ]; then
+  _whoami=$(id -un 2>/dev/null || echo "")
+  if [ -n "$_whoami" ] && command -v getent >/dev/null 2>&1; then
+    HOME=$(getent passwd "$_whoami" 2>/dev/null | cut -d: -f6)
+  elif [ -n "$_whoami" ] && command -v dscl >/dev/null 2>&1; then
+    HOME=$(dscl . -read "/Users/$_whoami" NFSHomeDirectory 2>/dev/null | awk '{print $2}')
+  fi
+  export HOME
+fi
+if [ -z "${HOME:-}" ] || [ ! -d "$HOME" ]; then
+  printf 'Error: could not determine your home directory ($HOME is unset).\n' >&2
+  exit 1
+fi
+
 MIN_NODE_MAJOR=18
 NODE_VERSION="22.14.0"
 BLOBY_HOME="$HOME/.bloby"
@@ -14,6 +31,11 @@ TOOLS_DIR="$BLOBY_HOME/tools"
 NODE_DIR="$TOOLS_DIR/node"
 BIN_DIR="$BLOBY_HOME/bin"
 USE_SYSTEM_NODE=false
+LIBC=""
+# Temp paths the cleanup trap removes — kept empty until we own them so an early
+# exit can never `rm -rf` an inherited value (e.g. the system $TMPDIR).
+WORK_DIR=""
+TMPFILE=""
 
 # Brand colors: #00ADFE (light) and #0158FB (deep) -- Morphy palette, 24-bit truecolor
 BLUE='\033[38;2;0;173;254m'
@@ -37,15 +59,47 @@ if [ ! -t 1 ]; then
   BLUE='' PINK='' YELLOW='' RED='' DIM='' BOLD='' RESET='' G1='' G2='' G3='' G4='' G5='' G6='' G7=''
 fi
 
-# Cleanup on exit (restore cursor, reset colors, remove temp files)
+# Cleanup on exit (restore cursor, reset colors, remove temp files).
+# Only remove paths we actually created — never an inherited/unset value.
 cleanup() {
   printf '\033[?25h'  # show cursor
   printf "${RESET}"
-  rm -f "$TMPFILE" 2>/dev/null
-  rm -rf "$TMPDIR" 2>/dev/null
+  [ -n "$TMPFILE" ] && rm -f "$TMPFILE" 2>/dev/null
+  [ -n "$WORK_DIR" ] && rm -rf "$WORK_DIR" 2>/dev/null
+  return 0
 }
 trap cleanup EXIT INT TERM
 
+# ─── Download + integrity helpers ───────────────────────────────────────────
+
+# download_file <url> <dest> — curl/wget with HTTPS floor, timeout, and retry.
+download_file() {
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL --proto '=https' --tlsv1.2 --connect-timeout 20 --retry 3 --retry-delay 2 -o "$2" "$1"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -q --https-only --tries=3 --timeout=20 -O "$2" "$1"
+  else
+    printf "  ${RED}✗${RESET}  curl or wget is required to install Bloby\n"
+    exit 1
+  fi
+}
+
+# verify_sha256 <file> <expected-hex> — 0 match, 1 mismatch, 2 no tool available.
+verify_sha256() {
+  _actual=""
+  if command -v sha256sum >/dev/null 2>&1; then
+    _actual=$(sha256sum "$1" 2>/dev/null | awk '{print $1}')
+  elif command -v shasum >/dev/null 2>&1; then
+    _actual=$(shasum -a 256 "$1" 2>/dev/null | awk '{print $1}')
+  else
+    return 2
+  fi
+  # No hash computed (tool failed / file vanished) → "skip" (2), not "mismatch" (1),
+  # so we warn rather than aborting with a misleading "tampered download".
+  [ -n "$_actual" ] || return 2
+  [ "$_actual" = "$2" ]
+}
+
 printf "\n"
 printf "${G1}${BOLD}                                █▄         ${RESET}\n"
 printf "${G2}${BOLD}      ▄              ▄          ██         ${RESET}\n"
@@ -83,6 +137,14 @@ detect_platform() {
       ;;
   esac
 
+  # Detect musl (Alpine): nodejs.org ships glibc builds only, so a bundled Node
+  # would segfault at runtime. Flag it now and require a system Node instead.
+  if [ "$PLATFORM" = "linux" ]; then
+    if [ -f /etc/alpine-release ] || (ldd --version 2>&1 | grep -qi musl); then
+      LIBC="musl"
+    fi
+  fi
+
   printf "  ${DIM}Platform: ${PLATFORM}/${NODEARCH}${RESET}\n"
 }
 
@@ -115,35 +177,68 @@ install_node() {
     fi
   fi
 
-  printf "  ${BLUE}↓${RESET}  Downloading Node.js v${NODE_VERSION}...\n"
+  # nodejs.org ships glibc-linked builds; on musl they segfault at runtime.
+  if [ "$LIBC" = "musl" ]; then
+    printf "  ${RED}✗${RESET}  Alpine/musl detected — Bloby's bundled Node.js requires glibc.\n"
+    printf "  ${DIM}Install Node.js >= ${MIN_NODE_MAJOR} (e.g. ${BOLD}apk add nodejs npm${RESET}${DIM}) and re-run this installer.${RESET}\n"
+    exit 1
+  fi
 
-  NODE_URL="https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-${PLATFORM}-${NODEARCH}.tar.xz"
-  TMPFILE=$(mktemp /tmp/node-XXXXXX.tar.xz)
+  printf "  ${BLUE}↓${RESET}  Downloading Node.js v${NODE_VERSION}...\n"
 
-  # Download
-  if command -v curl >/dev/null 2>&1; then
-    curl -fsSL -o "$TMPFILE" "$NODE_URL"
-  elif command -v wget >/dev/null 2>&1; then
-    wget -qO "$TMPFILE" "$NODE_URL"
+  NODE_FILE="node-v${NODE_VERSION}-${PLATFORM}-${NODEARCH}.tar.xz"
+  NODE_URL="https://nodejs.org/dist/v${NODE_VERSION}/${NODE_FILE}"
+  # Trailing X's, NO suffix: BSD mktemp (macOS) only substitutes trailing X's,
+  # so a ".tar.xz" suffix would create a literal, predictable, non-unique file.
+  TMPFILE=$(mktemp "${TMPDIR:-/tmp}/bloby-node-XXXXXX")
+  download_file "$NODE_URL" "$TMPFILE"
+
+  # Integrity: verify against nodejs.org SHASUMS256.txt before extracting. A
+  # mismatch is fatal; an unreachable sums file or missing hash tool degrades to
+  # a warning so installs still proceed (the download itself is TLS-protected).
+  printf "  ${DIM}Verifying download...${RESET}\n"
+  EXPECTED_SHA=""
+  SUMS=$(curl -fsSL --proto '=https' --tlsv1.2 --connect-timeout 20 "https://nodejs.org/dist/v${NODE_VERSION}/SHASUMS256.txt" 2>/dev/null \
+    || wget -q --https-only --timeout=20 -O- "https://nodejs.org/dist/v${NODE_VERSION}/SHASUMS256.txt" 2>/dev/null \
+    || echo "")
+  if [ -n "$SUMS" ]; then
+    EXPECTED_SHA=$(printf '%s\n' "$SUMS" | awk -v f="$NODE_FILE" '$2==f {print $1; exit}')
+  fi
+  if [ -n "$EXPECTED_SHA" ]; then
+    vrc=0
+    verify_sha256 "$TMPFILE" "$EXPECTED_SHA" || vrc=$?
+    if [ "$vrc" = "0" ]; then
+      printf "  ${BLUE}✔${RESET}  Checksum verified\n"
+    elif [ "$vrc" = "2" ]; then
+      printf "  ${YELLOW}!${RESET}  Could not compute checksum — skipping verification\n"
+    else
+      printf "  ${RED}✗${RESET}  Node.js checksum mismatch — aborting (corrupt or tampered download)\n"
+      exit 1
+    fi
   else
-    printf "  ${RED}✗${RESET}  curl or wget required\n"
-    exit 1
+    printf "  ${YELLOW}!${RESET}  Could not fetch checksums — skipping verification\n"
   fi
 
-  # Extract
+  # Extract into a staging dir, verify it runs, then atomically swap in. An
+  # interrupt mid-extract no longer wipes the existing (working) node.
   mkdir -p "$TOOLS_DIR"
-  rm -rf "$NODE_DIR"
-  mkdir -p "$NODE_DIR"
-
-  tar xf "$TMPFILE" -C "$NODE_DIR" --strip-components=1
-  rm -f "$TMPFILE"
-
-  # Verify
-  if [ ! -x "$NODE_DIR/bin/node" ]; then
-    printf "  ${RED}✗${RESET}  Node.js download failed\n"
+  NODE_NEW="$NODE_DIR.new"
+  rm -rf "$NODE_NEW"
+  mkdir -p "$NODE_NEW"
+  tar xf "$TMPFILE" -C "$NODE_NEW" --strip-components=1
+  rm -f "$TMPFILE"; TMPFILE=""
+
+  if ! "$NODE_NEW/bin/node" -v >/dev/null 2>&1; then
+    printf "  ${RED}✗${RESET}  Node.js download failed (extracted binary does not run)\n"
+    rm -rf "$NODE_NEW"
     exit 1
   fi
 
+  rm -rf "$NODE_DIR.old"
+  [ -e "$NODE_DIR" ] && mv "$NODE_DIR" "$NODE_DIR.old"
+  mv "$NODE_NEW" "$NODE_DIR"
+  rm -rf "$NODE_DIR.old"
+
   printf "  ${BLUE}✔${RESET}  Node.js v${NODE_VERSION} installed\n"
 }
 
@@ -174,19 +269,15 @@ install_bloby() {
     exit 1
   fi
 
-  # Download and extract tarball
-  TMPDIR=$(mktemp -d)
-  if command -v curl >/dev/null 2>&1; then
-    curl -fsSL -o "$TMPDIR/bloby.tgz" "$TARBALL_URL"
-  elif command -v wget >/dev/null 2>&1; then
-    wget -qO "$TMPDIR/bloby.tgz" "$TARBALL_URL"
-  fi
+  # Download and extract tarball (download_file guards on missing curl/wget)
+  WORK_DIR=$(mktemp -d)
+  download_file "$TARBALL_URL" "$WORK_DIR/bloby.tgz"
 
-  tar xzf "$TMPDIR/bloby.tgz" -C "$TMPDIR"
-  EXTRACTED="$TMPDIR/package"
+  tar xzf "$WORK_DIR/bloby.tgz" -C "$WORK_DIR"
+  EXTRACTED="$WORK_DIR/package"
 
   if [ ! -d "$EXTRACTED" ]; then
-    rm -rf "$TMPDIR"
+    rm -rf "$WORK_DIR"; WORK_DIR=""
     printf "  ${RED}✗${RESET}  Installation failed\n"
     exit 1
   fi
@@ -219,7 +310,7 @@ install_bloby() {
     fi
   fi
 
-  rm -rf "$TMPDIR"
+  rm -rf "$WORK_DIR"; WORK_DIR=""
 
   # Install dependencies inside ~/.bloby/
   # claude-agent-sdk 0.3.x moved @anthropic-ai/sdk + @modelcontextprotocol/sdk to
@@ -245,6 +336,15 @@ install_bloby() {
     WS_INSTALL_LOG=$(mktemp)
     if ! (cd "$BLOBY_HOME/workspace" && "$NPM" install --omit=dev > "$WS_INSTALL_LOG" 2>&1); then
       printf "  ${RED}✗${RESET}  Workspace dependency install failed:\n"
+      # Native modules (better-sqlite3 etc.) need a compiler toolchain — detect
+      # the common "missing build tools" failure and point at the exact fix.
+      if grep -qiE 'make: .*command not found|gyp ERR! find Python|no developer tools|xcode-select|command not found: make|g\+\+: not found' "$WS_INSTALL_LOG"; then
+        if [ "$PLATFORM" = "darwin" ]; then
+          printf "  ${YELLOW}!${RESET}  Native build tools missing. Run ${BOLD}xcode-select --install${RESET} then re-run this installer.\n"
+        else
+          printf "  ${YELLOW}!${RESET}  Native build tools missing. On Debian/Ubuntu: ${BOLD}sudo apt-get install -y build-essential python3${RESET}, then re-run.\n"
+        fi
+      fi
       cat "$WS_INSTALL_LOG"
       rm -f "$WS_INSTALL_LOG"
       exit 1
@@ -348,19 +448,34 @@ install_bloby
 create_wrapper
 setup_path
 
+# Smoke-test: the wrapper + node + cli must actually run, not just exist on disk.
+if ! "$BIN_DIR/bloby" --version >/dev/null 2>&1; then
+  printf "\n  ${RED}✗${RESET}  Bloby installed but failed to run (\`bloby --version\`).\n"
+  printf "  ${DIM}Open a NEW terminal and run ${BOLD}bloby --version${RESET}${DIM}; if it still fails, re-run this installer.${RESET}\n\n"
+  exit 1
+fi
+
 printf "\n"
-printf "  ${PINK}${BOLD}✔  Bloby is ready!${RESET}\n"
+printf "  ${PINK}${BOLD}✔  Bloby is installed!${RESET}\n"
 printf "\n"
-printf "  ${DIM}─────────────────────────────${RESET}\n"
-printf "  ${BOLD}Get started:${RESET}\n"
+printf "  ${BLUE}${BOLD}╭───────────────────────────────────────────────────────╮${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}                                                       ${RESET}${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}${BOLD}   NEXT STEP  -  type this, then press Enter:${RESET}          ${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}                                                       ${RESET}${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}${BLUE}${BOLD}       >  bloby init${RESET}                                   ${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}                                                       ${RESET}${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}${DIM}   ─────────────────────────────────────────────────${RESET}   ${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}                                                       ${RESET}${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}${YELLOW}${BOLD}   Not working?  (\"command not found\")${RESET}                 ${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}   Just open a NEW terminal window and run${RESET}             ${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}   bloby init  again.${RESET}                                  ${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}                                                       ${RESET}${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}╰───────────────────────────────────────────────────────╯${RESET}\n"
 printf "\n"
-printf "    ${BLUE}bloby init${RESET}      Set up your bot\n"
+printf "  ${DIM}Other commands:${RESET}\n"
 printf "    ${BLUE}bloby start${RESET}     Start your bot\n"
 printf "    ${BLUE}bloby status${RESET}    Check if it's running\n"
 printf "    ${BLUE}bloby help${RESET}      All commands\n"
 printf "\n"
-printf "  ${PINK}>${RESET} Run ${BLUE}bloby init${RESET} to begin.\n"
-printf "  ${DIM}(Open a new terminal if 'bloby' isn't found yet)${RESET}\n"
-printf "\n"
 printf "  ${DIM}https://bloby.bot${RESET}\n"
 printf "\n"

package/scripts/install.ps1

@@ -6,6 +6,30 @@
 
 $ErrorActionPreference = "Stop"
 
+# TLS 1.2 floor for Windows PowerShell 5.1 (which can default to TLS 1.0/1.1 and
+# fail against nodejs.org/npm). OR-in so we never DROP TLS 1.3 on PowerShell 7+.
+try {
+    [Net.ServicePointManager]::SecurityProtocol = `
+        [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+} catch {}
+
+# Get-Url <url> <outFile> — download with a timeout and up to 3 attempts so a
+# single transient blip doesn't abort the whole install. PS 5.1-compatible
+# (no -MaximumRetryCount, which is PowerShell 6+ only).
+function Get-Url($url, $outFile) {
+    $attempt = 0
+    while ($true) {
+        $attempt++
+        try {
+            Invoke-WebRequest -Uri $url -OutFile $outFile -UseBasicParsing -TimeoutSec 60
+            return
+        } catch {
+            if ($attempt -ge 3) { throw }
+            Start-Sleep -Seconds 2
+        }
+    }
+}
+
 $MIN_NODE_MAJOR = 18
 $NODE_VERSION = "22.14.0"
 $BLOBY_HOME = Join-Path $env:USERPROFILE ".bloby"
@@ -29,6 +53,8 @@ $G5 = "`e[38;2;1;116;252m"
 $G6 = "`e[38;2;1;102;251m"
 $G7 = "`e[38;2;1;88;251m"
 $BOLD = "`e[1m"
+$DIM = "`e[2m"
+$YELLOW = "`e[33m"
 $RSET = "`e[0m"
 
 # Use ANSI sequences for consistent rendering; fallback to plain if no VT support
@@ -123,25 +149,64 @@ function Install-Node {
 
     Write-Down "Downloading Node.js v${NODE_VERSION}..."
 
-    $nodeUrl = "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-win-${NODEARCH}.zip"
+    $nodeFile = "node-v${NODE_VERSION}-win-${NODEARCH}.zip"
+    $nodeUrl = "https://nodejs.org/dist/v${NODE_VERSION}/$nodeFile"
     $tmpFile = Join-Path ([System.IO.Path]::GetTempPath()) "node-bloby.zip"
 
-    Invoke-WebRequest -Uri $nodeUrl -OutFile $tmpFile -UseBasicParsing
+    Get-Url $nodeUrl $tmpFile
 
-    # Extract
-    New-Item -ItemType Directory -Path $TOOLS_DIR -Force | Out-Null
-    if (Test-Path $NODE_DIR) { Remove-Item $NODE_DIR -Recurse -Force }
+    # Integrity: verify against nodejs.org SHASUMS256.txt before extracting. A
+    # mismatch is fatal; an unreachable sums file degrades to a warning.
+    try {
+        $sums = (Invoke-WebRequest -Uri "https://nodejs.org/dist/v${NODE_VERSION}/SHASUMS256.txt" -UseBasicParsing -TimeoutSec 30).Content
+        $line = $sums -split "`n" | Where-Object { $_ -match ([regex]::Escape($nodeFile) + '\s*$') } | Select-Object -First 1
+        if ($line) {
+            $expectedHash = ($line -split '\s+')[0]
+            $actualHash = (Get-FileHash -Path $tmpFile -Algorithm SHA256).Hash
+            if ($actualHash -ieq $expectedHash) {
+                Write-Check "Checksum verified"
+            } else {
+                Write-Host "  ✗  Node.js checksum mismatch — aborting (corrupt or tampered download)" -ForegroundColor Red
+                Remove-Item $tmpFile -Force -ErrorAction SilentlyContinue
+                exit 1
+            }
+        } else {
+            Write-Host "  !  Could not find checksum entry — skipping verification" -ForegroundColor Yellow
+        }
+    } catch {
+        Write-Host "  !  Could not fetch checksums — skipping verification" -ForegroundColor Yellow
+    }
 
+    # Extract into a staging dir, verify it runs, then swap. Move-Item cannot
+    # overwrite a populated directory, so the existing node is moved aside and
+    # removed only AFTER the new tree is verified — an interrupt never strands us.
+    New-Item -ItemType Directory -Path $TOOLS_DIR -Force | Out-Null
     $tmpExtract = Join-Path ([System.IO.Path]::GetTempPath()) "node-bloby-extract"
     if (Test-Path $tmpExtract) { Remove-Item $tmpExtract -Recurse -Force }
 
     Expand-Archive -Path $tmpFile -DestinationPath $tmpExtract -Force
     $extracted = Get-ChildItem $tmpExtract | Select-Object -First 1
-    Move-Item -Path $extracted.FullName -Destination $NODE_DIR -Force
+    $nodeNew = "$NODE_DIR.new"
+    if (Test-Path $nodeNew) { Remove-Item $nodeNew -Recurse -Force }
+    Move-Item -Path $extracted.FullName -Destination $nodeNew -Force
 
     Remove-Item $tmpFile -Force -ErrorAction SilentlyContinue
     Remove-Item $tmpExtract -Recurse -Force -ErrorAction SilentlyContinue
 
+    $stagedNode = Join-Path $nodeNew "node.exe"
+    $stagedOk = $false
+    try { $stagedOk = [bool](& $stagedNode -v 2>$null) } catch {}
+    if (-not $stagedOk) {
+        Write-Host "  ✗  Node.js download failed (extracted binary does not run)" -ForegroundColor Red
+        Remove-Item $nodeNew -Recurse -Force -ErrorAction SilentlyContinue
+        exit 1
+    }
+
+    if (Test-Path "$NODE_DIR.old") { Remove-Item "$NODE_DIR.old" -Recurse -Force -ErrorAction SilentlyContinue }
+    if (Test-Path $NODE_DIR) { Move-Item $NODE_DIR "$NODE_DIR.old" -Force }
+    Move-Item $nodeNew $NODE_DIR -Force
+    if (Test-Path "$NODE_DIR.old") { Remove-Item "$NODE_DIR.old" -Recurse -Force -ErrorAction SilentlyContinue }
+
     # Verify
     $nodeBin = Join-Path $NODE_DIR "node.exe"
     if (-not (Test-Path $nodeBin)) {
@@ -172,9 +237,13 @@ function Install-Bloby {
 
     Write-Down "Installing bloby..."
 
-    $tarballUrl = (& $NPM view bloby-bot dist.tarball 2>$null).Trim()
+    # Capture first, THEN .Trim() — calling .Trim() on a null (offline npm) throws
+    # under $ErrorActionPreference='Stop' and skips the friendly message below.
+    $tarballUrl = ""
+    try { $tarballUrl = (& $NPM view bloby-bot dist.tarball 2>$null) } catch {}
+    if ($tarballUrl) { $tarballUrl = $tarballUrl.Trim() }
     if (-not $tarballUrl) {
-        Write-Host "  ✗  Failed to fetch package info from npm" -ForegroundColor Red
+        Write-Host "  ✗  Failed to fetch package info from npm (are you online?)" -ForegroundColor Red
         exit 1
     }
 
@@ -184,7 +253,7 @@ function Install-Bloby {
 
     try {
         $tarball = Join-Path $tmpDir "bloby.tgz"
-        Invoke-WebRequest -Uri $tarballUrl -OutFile $tarball -UseBasicParsing
+        Get-Url $tarballUrl $tarball
 
         tar xzf $tarball -C $tmpDir
 
@@ -253,21 +322,39 @@ function Install-Bloby {
     if (-not ((Test-Path $npmrc) -and (Select-String -Path $npmrc -Pattern '^legacy-peer-deps' -Quiet))) {
         Add-Content -Path $npmrc -Value 'legacy-peer-deps=true'
     }
+    # Toggle EAP to Continue around the native npm call so a stderr line doesn't
+    # raise a NativeCommandError; then gate on the real exit code. A broken dep
+    # tree is fatal here (matching install.sh) instead of being silently ignored.
     Push-Location $BLOBY_HOME
-    try {
-        & $NPM install --omit=dev 2>$null
-    } catch {}
+    $eap = $ErrorActionPreference; $ErrorActionPreference = "Continue"
+    $npmOut = & $NPM install --omit=dev 2>&1
+    $npmCode = $LASTEXITCODE
+    $ErrorActionPreference = $eap
     Pop-Location
+    if ($npmCode -ne 0) {
+        Write-Host "  ✗  Dependency install failed:" -ForegroundColor Red
+        $npmOut | ForEach-Object { Write-Host "     $_" }
+        exit 1
+    }
 
     # Install workspace dependencies (rebuilds native modules for this platform)
     $wsDir = Join-Path $BLOBY_HOME "workspace"
     if (Test-Path (Join-Path $wsDir "package.json")) {
         Write-Down "Installing workspace dependencies..."
         Push-Location $wsDir
-        try {
-            & $NPM install --omit=dev 2>$null
-        } catch {}
+        $eap = $ErrorActionPreference; $ErrorActionPreference = "Continue"
+        $wsOut = & $NPM install --omit=dev 2>&1
+        $wsCode = $LASTEXITCODE
+        $ErrorActionPreference = $eap
         Pop-Location
+        if ($wsCode -ne 0) {
+            Write-Host "  ✗  Workspace dependency install failed:" -ForegroundColor Red
+            if ("$wsOut" -match 'Visual Studio|gyp ERR|MSBuild|node-gyp|Python') {
+                Write-Host "  !  Native build tools missing. Install the Visual Studio Build Tools (Desktop C++ workload) + Python 3, then re-run. See https://github.com/nodejs/node-gyp#on-windows" -ForegroundColor Yellow
+            }
+            $wsOut | ForEach-Object { Write-Host "     $_" }
+            exit 1
+        }
     }
 
     # Verify
@@ -334,33 +421,63 @@ Install-Bloby
 Create-Wrapper
 Setup-Path
 
+# Smoke-test: the wrapper + node + cli must actually run, not just exist on disk.
+$blobyCmd = Join-Path $BIN_DIR "bloby.cmd"
+$smokeOk = $false
+try { $smokeOk = [bool](& $blobyCmd --version 2>$null) } catch {}
+if (-not $smokeOk) {
+    Write-Host ""
+    Write-Host "  ✗  Bloby installed but failed to run (bloby --version)." -ForegroundColor Red
+    Write-Host "     Open a NEW terminal and run 'bloby --version'; if it still fails, re-run this installer." -ForegroundColor DarkGray
+    exit 1
+}
+
 Write-Host ""
 if ($vtSupported) {
-    Write-Host "  ${PINK}${BOLD}✔  Bloby is ready!${RSET}"
+    Write-Host "  ${PINK}${BOLD}✔  Bloby is installed!${RSET}"
 } else {
-    Write-Host "  ✔  Bloby is ready!" -ForegroundColor Magenta
+    Write-Host "  ✔  Bloby is installed!" -ForegroundColor Magenta
 }
 Write-Host ""
-Write-Host "  -----------------------------" -ForegroundColor DarkGray
-Write-Host "  Get started:"
+if ($vtSupported) {
+    Write-Host "  ${BLUE}${BOLD}╭───────────────────────────────────────────────────────╮${RSET}"
+    Write-Host "  ${BLUE}${BOLD}│${RSET}                                                       ${RSET}${BLUE}${BOLD}│${RSET}"
+    Write-Host "  ${BLUE}${BOLD}│${RSET}${BOLD}   NEXT STEP  -  type this, then press Enter:${RSET}          ${BLUE}${BOLD}│${RSET}"
+    Write-Host "  ${BLUE}${BOLD}│${RSET}                                                       ${RSET}${BLUE}${BOLD}│${RSET}"
+    Write-Host "  ${BLUE}${BOLD}│${RSET}${BLUE}${BOLD}       >  bloby init${RSET}                                   ${BLUE}${BOLD}│${RSET}"
+    Write-Host "  ${BLUE}${BOLD}│${RSET}                                                       ${RSET}${BLUE}${BOLD}│${RSET}"
+    Write-Host "  ${BLUE}${BOLD}│${RSET}${DIM}   ─────────────────────────────────────────────────${RSET}   ${BLUE}${BOLD}│${RSET}"
+    Write-Host "  ${BLUE}${BOLD}│${RSET}                                                       ${RSET}${BLUE}${BOLD}│${RSET}"
+    Write-Host "  ${BLUE}${BOLD}│${RSET}${YELLOW}${BOLD}   Not working?  (`"command not found`")${RSET}                 ${BLUE}${BOLD}│${RSET}"
+    Write-Host "  ${BLUE}${BOLD}│${RSET}   Just open a NEW terminal window and run${RSET}             ${BLUE}${BOLD}│${RSET}"
+    Write-Host "  ${BLUE}${BOLD}│${RSET}   bloby init  again.${RSET}                                  ${BLUE}${BOLD}│${RSET}"
+    Write-Host "  ${BLUE}${BOLD}│${RSET}                                                       ${RSET}${BLUE}${BOLD}│${RSET}"
+    Write-Host "  ${BLUE}${BOLD}╰───────────────────────────────────────────────────────╯${RSET}"
+} else {
+    Write-Host "  +-------------------------------------------------------+" -ForegroundColor Cyan
+    Write-Host "  |                                                       |" -ForegroundColor Cyan
+    Write-Host "  |   NEXT STEP  -  type this, then press Enter:          |" -ForegroundColor Cyan
+    Write-Host "  |                                                       |" -ForegroundColor Cyan
+    Write-Host "  |       >  bloby init                                   |" -ForegroundColor Cyan
+    Write-Host "  |                                                       |" -ForegroundColor Cyan
+    Write-Host "  |   Not working?  (`"command not found`")                 |" -ForegroundColor Cyan
+    Write-Host "  |   Just open a NEW terminal window and run             |" -ForegroundColor Cyan
+    Write-Host "  |   bloby init  again.                                  |" -ForegroundColor Cyan
+    Write-Host "  |                                                       |" -ForegroundColor Cyan
+    Write-Host "  +-------------------------------------------------------+" -ForegroundColor Cyan
+}
 Write-Host ""
 if ($vtSupported) {
-    Write-Host "    ${BLUE}bloby init${RSET}      Set up your bot"
+    Write-Host "  ${DIM}Other commands:${RSET}"
     Write-Host "    ${BLUE}bloby start${RSET}     Start your bot"
     Write-Host "    ${BLUE}bloby status${RSET}    Check if it's running"
-    Write-Host ""
-    Write-Host "  ${PINK}>${RSET} Run ${BLUE}bloby init${RSET} to begin."
+    Write-Host "    ${BLUE}bloby help${RSET}      All commands"
 } else {
-    Write-Host "    bloby init      " -ForegroundColor Cyan -NoNewline; Write-Host "Set up your bot"
+    Write-Host "  Other commands:" -ForegroundColor DarkGray
     Write-Host "    bloby start     " -ForegroundColor Cyan -NoNewline; Write-Host "Start your bot"
     Write-Host "    bloby status    " -ForegroundColor Cyan -NoNewline; Write-Host "Check if it's running"
-    Write-Host ""
-    Write-Host "  > " -ForegroundColor Magenta -NoNewline
-    Write-Host "Run " -NoNewline
-    Write-Host "bloby init" -ForegroundColor Cyan -NoNewline
-    Write-Host " to begin."
+    Write-Host "    bloby help      " -ForegroundColor Cyan -NoNewline; Write-Host "All commands"
 }
-Write-Host "  (Open a new terminal if 'bloby' isn't found yet)" -ForegroundColor DarkGray
 Write-Host ""
 Write-Host "  https://bloby.bot" -ForegroundColor DarkGray
 Write-Host ""