deploy: modularize bin shell scripts with shared helpers (#109)

Author: benvinegar

AGENTS.md

@@ -182,6 +182,8 @@ Add new test files to `vitest.config.mjs` (and shell wrappers under `test/` as n
 - Security functions must be pure, testable modules (no side effects, no env vars at module scope).
 - All security code must have tests before merging.
 - Run `bin/security-audit.sh --deep` after any security-relevant changes.
+- Keep shell CLIs thin: move reusable logic to `bin/lib/*.sh`, and source shared helpers (`shell-common.sh`, `release-common.sh`, `deploy-common.sh`, `doctor-common.sh`) instead of duplicating logging/error/root-check patterns.
+- For shell scripts, standardize on `bb_enable_strict_mode` and shared helper functions (`bb_log`, `bb_die`, etc.) rather than ad-hoc wrappers.
 - Protected files (`tool-guard.ts`, `security.mjs`, their tests) are deployed read-only. The agent cannot modify them at runtime.
 - New integrations get their own subdirectory (e.g. `discord-bridge/`).
 - Extensions are deployed from `pi/extensions/` → agent's `~/.pi/agent/extensions/`.

README.md

@@ -162,6 +162,23 @@ See [SECURITY.md](SECURITY.md) for full threat model, trust boundaries, and know
 - [SECURITY.md](SECURITY.md) — deep security model and vulnerability reporting
 - [CONTRIBUTING.md](CONTRIBUTING.md) — contribution workflow
 
+## Shell script architecture
+
+Operational shell scripts under `bin/` follow a shared module pattern to keep command entrypoints thin and behavior consistent:
+
+- shared safety/logging/error helpers in `bin/lib/shell-common.sh`
+- release lifecycle helpers in `bin/lib/release-common.sh`
+- deploy-specific helpers in `bin/lib/deploy-common.sh`
+- doctor output/counter helpers in `bin/lib/doctor-common.sh`
+- JSON parsing helpers in `bin/lib/json-common.sh`
+
+Conventions:
+
+- source shared modules near the top of each script
+- call `bb_enable_strict_mode` (strict bash mode)
+- prefer shared `bb_log`/`bb_die` helpers instead of ad-hoc logging/error code
+- keep heavy logic in `bin/lib/*` and keep CLI-facing scripts focused on orchestration
+
 ## Tests
 
 ```bash

bin/config.sh

@@ -7,7 +7,10 @@
 #
 # Can be re-run to update existing config. Existing values shown as defaults.
 
-set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=bin/lib/shell-common.sh
+source "$SCRIPT_DIR/lib/shell-common.sh"
+bb_enable_strict_mode
 
 # ── Formatting ───────────────────────────────────────────────────────────────
 

bin/deploy.sh

@@ -20,12 +20,17 @@ AGENT_USER="baudbot_agent"
 DRY_RUN=0
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
+# shellcheck source=bin/lib/shell-common.sh
+source "$SCRIPT_DIR/lib/shell-common.sh"
 # shellcheck source=bin/lib/json-common.sh
 source "$SCRIPT_DIR/lib/json-common.sh"
+# shellcheck source=bin/lib/deploy-common.sh
+source "$SCRIPT_DIR/lib/deploy-common.sh"
+bb_enable_strict_mode
 
 # Helper: run a command as baudbot_agent
 as_agent() {
-  sudo -u "$AGENT_USER" "$@"
+  bb_as_user "$AGENT_USER" "$@"
 }
 
 for arg in "$@"; do
@@ -34,32 +39,18 @@ for arg in "$@"; do
   esac
 done
 
+command -v sudo >/dev/null 2>&1 || bb_die "deploy requires sudo in PATH"
+[ -d "$BAUDBOT_SRC" ] || bb_die "source repo not found: $BAUDBOT_SRC"
+
 # Determine admin config location (used for secret deploy + feature flags)
-if [ -n "${BAUDBOT_CONFIG_USER:-}" ]; then
-  DEPLOY_USER="$BAUDBOT_CONFIG_USER"
-elif [ -n "${SUDO_USER:-}" ] && [ "${SUDO_USER:-}" != "root" ]; then
-  DEPLOY_USER="$SUDO_USER"
-else
-  DEPLOY_USER=$(stat -c '%U' "$BAUDBOT_SRC" 2>/dev/null || echo "")
-  if [ -z "$DEPLOY_USER" ] || [ "$DEPLOY_USER" = "root" ]; then
-    DEPLOY_USER="$(whoami)"
-  fi
-fi
+DEPLOY_USER="$(bb_resolve_deploy_user "$BAUDBOT_SRC")"
 DEPLOY_HOME=$(getent passwd "$DEPLOY_USER" | cut -d: -f6 2>/dev/null || echo "")
 ADMIN_CONFIG="$DEPLOY_HOME/.baudbot/.env"
 RENDER_ENV_SCRIPT="$BAUDBOT_SRC/bin/render-env.sh"
 
 source_env_value() {
   local key="$1"
-  if [ -x "$RENDER_ENV_SCRIPT" ]; then
-    BAUDBOT_ADMIN_HOME="$DEPLOY_HOME" BAUDBOT_CONFIG_USER="$DEPLOY_USER" "$RENDER_ENV_SCRIPT" --get "$key" 2>/dev/null || true
-    return 0
-  fi
-  if [ -f "$ADMIN_CONFIG" ]; then
-    grep -E "^${key}=" "$ADMIN_CONFIG" | tail -n 1 | cut -d= -f2- || true
-    return 0
-  fi
-  return 0
+  bb_source_env_value "$RENDER_ENV_SCRIPT" "$DEPLOY_HOME" "$DEPLOY_USER" "$ADMIN_CONFIG" "$key"
 }
 
 EXPERIMENTAL_MODE="${BAUDBOT_EXPERIMENTAL:-}"
@@ -71,7 +62,7 @@ case "$EXPERIMENTAL_MODE" in
   *) EXPERIMENTAL_MODE=0 ;;
 esac
 
-log() { echo "  $1"; }
+log() { bb_log "$1"; }
 
 # Security-critical files — deployed read-only (chmod a-w)
 PROTECTED_EXTENSIONS=(tool-guard.ts tool-guard.test.mjs)
@@ -112,8 +103,6 @@ if [ "$DRY_RUN" -eq 0 ]; then
   as_agent chmod u+w "$BAUDBOT_HOME/.pi/agent/baudbot-manifest.json" 2>/dev/null || true
 fi
 
-set -euo pipefail
-
 # ── Extensions ───────────────────────────────────────────────────────────────
 
 echo "Deploying extensions..."

bin/doctor.sh

@@ -4,7 +4,12 @@
 #
 # Usage: baudbot doctor [--fix]
 
-set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=bin/lib/shell-common.sh
+source "$SCRIPT_DIR/lib/shell-common.sh"
+# shellcheck source=bin/lib/doctor-common.sh
+source "$SCRIPT_DIR/lib/doctor-common.sh"
+bb_enable_strict_mode
 
 for arg in "$@"; do
   case "$arg" in
@@ -16,17 +21,15 @@ for arg in "$@"; do
 done
 
 BAUDBOT_HOME="/home/baudbot_agent"
-PASS=0
-FAIL=0
-WARN=0
+doctor_init_counters
 IS_ROOT=0
 if [ "$(id -u)" -eq 0 ]; then
   IS_ROOT=1
 fi
 
-pass() { echo "  ✓ $1"; PASS=$((PASS + 1)); }
-fail() { echo "  ✗ $1"; FAIL=$((FAIL + 1)); }
-warn() { echo "  ⚠ $1"; WARN=$((WARN + 1)); }
+pass() { doctor_pass "$1"; }
+fail() { doctor_fail "$1"; }
+warn() { doctor_warn "$1"; }
 
 echo "Baudbot Doctor"
 echo ""
@@ -103,10 +106,10 @@ echo "Admin config:"
 
 # Check for admin config/env source
 ADMIN_USER="${SUDO_USER:-$(whoami)}"
-ADMIN_HOME=$(getent passwd "$ADMIN_USER" | cut -d: -f6 2>/dev/null || echo "")
+ADMIN_HOME="$(bb_resolve_user_home "$ADMIN_USER" || true)"
 ADMIN_CONFIG="$ADMIN_HOME/.baudbot/.env"
 BACKEND_CONF="$ADMIN_HOME/.baudbot/env-store.conf"
-RENDER_ENV_SCRIPT="${BAUDBOT_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}/bin/render-env.sh"
+RENDER_ENV_SCRIPT="${BAUDBOT_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}/bin/render-env.sh"
 
 ADMIN_BACKEND="file"
 if [ -f "$BACKEND_CONF" ]; then
@@ -139,21 +142,10 @@ if [ -f "$ENV_FILE" ]; then
     fail ".env owned by $OWNER (should be baudbot_agent)"
   fi
 
-  env_value() {
-    local key="$1"
-    local line
-    line=$(grep -E "^${key}=" "$ENV_FILE" 2>/dev/null | tail -n 1 || true)
-    if [ -z "$line" ]; then
-      echo ""
-      return 0
-    fi
-    echo "${line#*=}"
-  }
-
   # LLM key validation: require at least one valid key, and flag malformed configured keys.
   VALID_LLM_COUNT=0
 
-  ANTHROPIC_VALUE="$(env_value ANTHROPIC_API_KEY)"
+  ANTHROPIC_VALUE="$(bb_read_env_value "$ENV_FILE" ANTHROPIC_API_KEY)"
   if [ -n "$ANTHROPIC_VALUE" ]; then
     if [[ "$ANTHROPIC_VALUE" == sk-ant-* ]]; then
       VALID_LLM_COUNT=$((VALID_LLM_COUNT + 1))
@@ -162,7 +154,7 @@ if [ -f "$ENV_FILE" ]; then
     fi
   fi
 
-  OPENAI_VALUE="$(env_value OPENAI_API_KEY)"
+  OPENAI_VALUE="$(bb_read_env_value "$ENV_FILE" OPENAI_API_KEY)"
   if [ -n "$OPENAI_VALUE" ]; then
     if [[ "$OPENAI_VALUE" == sk-* ]]; then
       VALID_LLM_COUNT=$((VALID_LLM_COUNT + 1))
@@ -171,12 +163,12 @@ if [ -f "$ENV_FILE" ]; then
     fi
   fi
 
-  GEMINI_VALUE="$(env_value GEMINI_API_KEY)"
+  GEMINI_VALUE="$(bb_read_env_value "$ENV_FILE" GEMINI_API_KEY)"
   if [ -n "$GEMINI_VALUE" ]; then
     VALID_LLM_COUNT=$((VALID_LLM_COUNT + 1))
   fi
 
-  OPENCODE_VALUE="$(env_value OPENCODE_ZEN_API_KEY)"
+  OPENCODE_VALUE="$(bb_read_env_value "$ENV_FILE" OPENCODE_ZEN_API_KEY)"
   if [ -n "$OPENCODE_VALUE" ]; then
     VALID_LLM_COUNT=$((VALID_LLM_COUNT + 1))
   fi
@@ -199,15 +191,15 @@ if [ -f "$ENV_FILE" ]; then
 
   BROKER_MODE_READY=true
   for key in "${BROKER_REQUIRED_KEYS[@]}"; do
-    if [ -z "$(env_value "$key")" ]; then
+    if [ -z "$(bb_read_env_value "$ENV_FILE" "$key")" ]; then
       BROKER_MODE_READY=false
       break
     fi
   done
 
   SOCKET_MODE_READY=true
   for key in SLACK_BOT_TOKEN SLACK_APP_TOKEN; do
-    if [ -z "$(env_value "$key")" ]; then
+    if [ -z "$(bb_read_env_value "$ENV_FILE" "$key")" ]; then
       SOCKET_MODE_READY=false
       break
     fi
@@ -216,15 +208,15 @@ if [ -f "$ENV_FILE" ]; then
   if [ "$BROKER_MODE_READY" = true ]; then
     pass "broker mode configured (SLACK_BROKER_*)"
     for key in SLACK_BOT_TOKEN SLACK_APP_TOKEN; do
-      if [ -n "$(env_value "$key")" ]; then
+      if [ -n "$(bb_read_env_value "$ENV_FILE" "$key")" ]; then
         pass "$key is set"
       else
         pass "$key not required in broker mode"
       fi
     done
   else
     for key in SLACK_BOT_TOKEN SLACK_APP_TOKEN; do
-      if [ -n "$(env_value "$key")" ]; then
+      if [ -n "$(bb_read_env_value "$ENV_FILE" "$key")" ]; then
         pass "$key is set"
       else
         warn "$key is not set"
@@ -357,7 +349,7 @@ fi
 echo ""
 echo "Agent:"
 
-if command -v systemctl &>/dev/null && [ -d /run/systemd/system ]; then
+if bb_has_systemd; then
   enabled_state=$(systemctl is-enabled baudbot 2>&1 || true)
   if [ "$enabled_state" = "enabled" ]; then
     pass "systemd unit enabled"
@@ -432,20 +424,4 @@ fi
 
 # ── Summary ──────────────────────────────────────────────────────────────────
 
-echo ""
-echo "────────────────────────────"
-echo "  $PASS passed, $FAIL failed, $WARN warnings"
-
-if [ "$FAIL" -gt 0 ]; then
-  echo ""
-  echo "Fix failures before starting the agent."
-  exit 1
-elif [ "$WARN" -gt 0 ]; then
-  echo ""
-  echo "Warnings are non-blocking but should be reviewed."
-  exit 0
-else
-  echo ""
-  echo "All checks passed."
-  exit 0
-fi
+doctor_summary_and_exit