shipwright-cli 3.1.0 → 3.3.0

package/scripts/sw-fix.sh

@@ -6,7 +6,8 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="3.1.0"
+# shellcheck disable=SC2034
+VERSION="3.3.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # ─── Cross-platform compatibility ──────────────────────────────────────────
@@ -43,6 +44,8 @@ REPOS=()
 REPOS_FROM=""
 TEMPLATE="fast"
 MODEL=""
+EFFORT_LEVEL=""
+FALLBACK_MODEL=""
 MAX_PARALLEL=3
 DRY_RUN=false
 BRANCH_PREFIX="fix/"
@@ -60,6 +63,8 @@ show_help() {
     echo -e "  ${DIM}--repos-from file${RESET}         Read repo paths from file (one per line)"
     echo -e "  ${DIM}--pipeline template${RESET}       Pipeline template (default: fast)"
     echo -e "  ${DIM}--model model${RESET}             Model to use (default: auto)"
+    echo -e "  ${DIM}--effort level${RESET}              Effort level: low, medium, high"
+    echo -e "  ${DIM}--fallback-model model${RESET}      Fallback model on rate limits (default: sonnet)"
     echo -e "  ${DIM}--max-parallel N${RESET}          Max concurrent pipelines (default: 3)"
     echo -e "  ${DIM}--branch-prefix prefix${RESET}    Branch name prefix (default: \"fix/\")"
     echo -e "  ${DIM}--dry-run${RESET}                 Show what would happen without executing"
@@ -94,6 +99,14 @@ parse_args() {
                 MODEL="$2"
                 shift 2
                 ;;
+            --effort)
+                EFFORT_LEVEL="$2"
+                shift 2
+                ;;
+            --fallback-model)
+                FALLBACK_MODEL="$2"
+                shift 2
+                ;;
             --max-parallel)
                 MAX_PARALLEL="$2"
                 shift 2
@@ -222,6 +235,7 @@ fix_start() {
     local sanitized
     sanitized=$(sanitize_branch "$GOAL")
     local branch_name="${BRANCH_PREFIX}${sanitized}"
+    # shellcheck disable=SC2155
     local session_id="fix-$(date +%s)"
     local state_file="$FIX_DIR/${session_id}.json"
     local log_dir="$FIX_DIR/${session_id}-logs"
@@ -242,6 +256,8 @@ fix_start() {
     echo -e "  ${BOLD}Branch:${RESET}     $branch_name"
     echo -e "  ${BOLD}Parallel:${RESET}   $MAX_PARALLEL"
     [[ -n "$MODEL" ]] && echo -e "  ${BOLD}Model:${RESET}      $MODEL"
+    [[ -n "$EFFORT_LEVEL" ]] && echo -e "  ${BOLD}Effort:${RESET}     $EFFORT_LEVEL"
+    [[ -n "$FALLBACK_MODEL" ]] && echo -e "  ${BOLD}Fallback:${RESET}   $FALLBACK_MODEL"
     echo ""
 
     # ─── Dry Run ────────────────────────────────────────────────────────────
@@ -289,6 +305,7 @@ fix_start() {
 
     # ─── Parallel Execution ─────────────────────────────────────────────────
     local pids=()
+    # shellcheck disable=SC2034
     local pid_to_idx=()
     local idx=0
 
@@ -335,6 +352,8 @@ fix_start() {
             # Build pipeline command
             local cmd=("$SCRIPT_DIR/sw-pipeline.sh" start --goal "$GOAL" --pipeline "$TEMPLATE" --skip-gates)
             [[ -n "$MODEL" ]] && cmd+=(--model "$MODEL")
+            [[ -n "$EFFORT_LEVEL" ]] && cmd+=(--effort "$EFFORT_LEVEL")
+            [[ -n "$FALLBACK_MODEL" ]] && cmd+=(--fallback-model "$FALLBACK_MODEL")
 
             # Run pipeline
             "${cmd[@]}"

package/scripts/sw-fleet-discover.sh

@@ -6,8 +6,9 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="3.1.0"
+VERSION="3.3.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC2034
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 # ─── Cross-platform compatibility ──────────────────────────────────────────
@@ -29,6 +30,7 @@ fi
 if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
   emit_event() {
     local event_type="$1"; shift; mkdir -p "${HOME}/.shipwright"
+    # shellcheck disable=SC2155
     local payload="{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"type\":\"$event_type\""
     while [[ $# -gt 0 ]]; do local key="${1%%=*}" val="${1#*=}"; payload="${payload},\"${key}\":\"${val}\""; shift; done
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
@@ -118,6 +120,7 @@ discover_repos() {
 
     # Paginate through org repos
     local page=1
+    # shellcheck disable=SC2034
     local per_page=100
     local total_found=0
     local has_more=true
@@ -150,6 +153,7 @@ discover_repos() {
 
             name=$(echo "$repo_data" | jq -r '.name // ""')
             full_name=$(echo "$repo_data" | jq -r '.full_name // ""')
+            # shellcheck disable=SC2034
             url=$(echo "$repo_data" | jq -r '.url // ""')
             archived=$(echo "$repo_data" | jq -r '.archived // false')
             disabled=$(echo "$repo_data" | jq -r '.disabled // false')
@@ -376,7 +380,7 @@ merge_into_config() {
 
     # Merge into config
     local tmp_config="${config_path}.tmp.$$"
-    local updated_config=$(cat "$config_path")
+    local updated_config; updated_config=$(cat "$config_path")
 
     for repo_path in "${repos_to_add[@]}"; do
         updated_config=$(echo "$updated_config" | jq \

package/scripts/sw-fleet-viz.sh

@@ -6,8 +6,9 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="3.1.0"
+VERSION="3.3.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC2034
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 # ─── Cross-platform compatibility ──────────────────────────────────────────
@@ -31,6 +32,7 @@ fi
 if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
   emit_event() {
     local event_type="$1"; shift; mkdir -p "${HOME}/.shipwright"
+    # shellcheck disable=SC2155
     local payload="{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"type\":\"$event_type\""
     while [[ $# -gt 0 ]]; do local key="${1%%=*}" val="${1#*=}"; payload="${payload},\"${key}\":\"${val}\""; shift; done
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
@@ -156,6 +158,7 @@ show_workers() {
     echo ""
 
     # Get per-repo worker counts
+    # shellcheck disable=SC2034
     local total_workers_allocated=0
     jq -r '.active_jobs[]? | .repo' "$FLEET_STATE" 2>/dev/null | sort -u | while read -r repo; do
         local worker_count job_count utilization
@@ -176,7 +179,7 @@ show_workers() {
     echo -e "${BOLD}Remote Machines:${RESET}"
     echo ""
 
-    if jq '.machines[]?' "$MACHINES_FILE" 2>/dev/null | grep -q .; then
+    if jq '.machines[]?' "$MACHINES_FILE" 2>/dev/null | grep -q . 2>/dev/null; then
         jq -r '.machines[]? | "\(.name) (\(.hostname)) — \(.status) — \(.active_jobs // 0) active"' "$MACHINES_FILE" 2>/dev/null | while read -r machine; do
             echo -e "  ${machine}"
         done
@@ -205,8 +208,10 @@ show_insights() {
 
     # Fleet-wide success rate (last 30 days)
     local total_pipelines successful_pipelines
-    total_pipelines=$(grep '"type":"pipeline.completed"' "$EVENTS_FILE" 2>/dev/null | tail -5000 | wc -l || echo "0")
-    successful_pipelines=$(grep '"type":"pipeline.completed".*"status":"success"' "$EVENTS_FILE" 2>/dev/null | tail -5000 | wc -l || echo "0")
+    total_pipelines=$(grep '"type":"pipeline.completed"' "$EVENTS_FILE" 2>/dev/null | tail -5000 | wc -l || true)
+    total_pipelines="${total_pipelines:-0}"
+    successful_pipelines=$(grep '"type":"pipeline.completed".*"status":"success"' "$EVENTS_FILE" 2>/dev/null | tail -5000 | wc -l || true)
+    successful_pipelines="${successful_pipelines:-0}"
 
     local success_rate=0
     if [[ "$total_pipelines" -gt 0 ]]; then

package/scripts/sw-fleet.sh

@@ -6,8 +6,9 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="3.1.0"
+VERSION="3.3.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC2034
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 # ─── Cross-platform compatibility ──────────────────────────────────────────
@@ -29,6 +30,7 @@ fi
 if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
   emit_event() {
     local event_type="$1"; shift; mkdir -p "${HOME}/.shipwright"
+    # shellcheck disable=SC2155
     local payload="{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"type\":\"$event_type\""
     while [[ $# -gt 0 ]]; do local key="${1%%=*}" val="${1#*=}"; payload="${payload},\"${key}\":\"${val}\""; shift; done
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
@@ -357,6 +359,7 @@ fleet_rebalance() {
         # When intelligence weighting is active, use weighted demand
         local allocated_total=0
         local alloc_list=()
+        # shellcheck disable=SC2034
         local use_weight="$total_weight"
         local effective_total="$total_demand"
         if [[ "$intel_weighting" == "true" && "$total_weight" -gt 0 ]]; then
@@ -768,6 +771,7 @@ fleet_start() {
     default_max_parallel=$(jq -r '.defaults.max_parallel // 2' "$config_file")
     default_model=$(jq -r '.defaults.model // "opus"' "$config_file")
     local shared_events
+    # shellcheck disable=SC2034
     shared_events=$(jq -r '.shared_events // true' "$config_file")
 
     mkdir -p "$FLEET_DIR"

package/scripts/sw-github-app.sh

@@ -6,8 +6,10 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="3.1.0"
+# shellcheck disable=SC2034
+VERSION="3.3.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC2034
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 # ─── Cross-platform compatibility ──────────────────────────────────────────
@@ -29,6 +31,7 @@ fi
 if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
   emit_event() {
     local event_type="$1"; shift; mkdir -p "${HOME}/.shipwright"
+    # shellcheck disable=SC2155
     local payload="{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"type\":\"$event_type\""
     while [[ $# -gt 0 ]]; do local key="${1%%=*}" val="${1#*=}"; payload="${payload},\"${key}\":\"${val}\""; shift; done
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
@@ -80,7 +83,9 @@ cmd_setup() {
     # Create config atomically
     local tmp_config
     tmp_config=$(mktemp)
+    # shellcheck disable=SC2064
     trap "rm -f '$tmp_config'" RETURN
+    # shellcheck disable=SC2046
     jq -n \
         --arg app_id "$app_id" \
         --arg key_path "$key_path" \
@@ -185,13 +190,21 @@ _cache_token() {
 
     local tmp_tokens
     tmp_tokens=$(mktemp)
+    # shellcheck disable=SC2064
     trap "rm -f '$tmp_tokens'" RETURN
 
+    local new_entry
+    new_entry=$(jq -n \
+        --argjson installation_id "$installation_id" \
+        --arg token "$token" \
+        --arg expires_at "$expires_at" \
+        '{installation_id: $installation_id, token: $token, expires_at: $expires_at}')
+
     if [[ -f "$TOKENS_FILE" ]]; then
-        jq ".tokens += [{\"installation_id\":$installation_id,\"token\":\"$token\",\"expires_at\":\"$expires_at\"}]" \
+        jq --argjson entry "$new_entry" '.tokens += [$entry]' \
             "$TOKENS_FILE" > "$tmp_tokens"
     else
-        jq -n ".tokens = [{\"installation_id\":$installation_id,\"token\":\"$token\",\"expires_at\":\"$expires_at\"}]" \
+        jq -n --argjson entry "$new_entry" '.tokens = [$entry]' \
             > "$tmp_tokens"
     fi
 
@@ -454,7 +467,8 @@ cmd_status() {
     # Show recent webhook events
     if [[ -f "$WEBHOOK_LOG" ]]; then
         local count
-        count=$(wc -l < "$WEBHOOK_LOG" 2>/dev/null || echo 0)
+        count=$(wc -l < "$WEBHOOK_LOG" 2>/dev/null || true)
+        count="${count:-0}"
         if [[ "$count" -gt 0 ]]; then
             echo -e "${BOLD}Recent Webhook Events (last 10):${RESET}"
             tail -10 "$WEBHOOK_LOG" | jq '{timestamp, event_type}' -c

package/scripts/sw-github-checks.sh

@@ -6,7 +6,7 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="3.1.0"
+VERSION="3.3.0"
 SCRIPT_DIR="${SCRIPT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}"
 REPO_DIR="${REPO_DIR:-$(cd "$SCRIPT_DIR/.." && pwd)}"
 
@@ -29,6 +29,7 @@ fi
 if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
   emit_event() {
     local event_type="$1"; shift; mkdir -p "${HOME}/.shipwright"
+    # shellcheck disable=SC2155
     local payload="{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"type\":\"$event_type\""
     while [[ $# -gt 0 ]]; do local key="${1%%=*}" val="${1#*=}"; payload="${payload},\"${key}\":\"${val}\""; shift; done
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
@@ -142,7 +143,7 @@ gh_checks_create_run() {
     if [[ "$result" -ne 0 ]]; then
         warn "Failed to create check run '${name}' (API returned ${result})" >&2
         echo ""
-        return 0
+        return 1
     fi
 
     local run_id

package/scripts/sw-github-deploy.sh

@@ -6,7 +6,7 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="3.1.0"
+VERSION="3.3.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
@@ -29,6 +29,7 @@ fi
 if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
   emit_event() {
     local event_type="$1"; shift; mkdir -p "${HOME}/.shipwright"
+    # shellcheck disable=SC2155
     local payload="{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"type\":\"$event_type\""
     while [[ $# -gt 0 ]]; do local key="${1%%=*}" val="${1#*=}"; payload="${payload},\"${key}\":\"${val}\""; shift; done
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
@@ -95,7 +96,7 @@ gh_deploy_create() {
     if [[ "$result" -ne 0 ]]; then
         warn "Failed to create deployment for ref '${ref}' to '${environment}' (API returned ${result})" >&2
         echo ""
-        return 0
+        return 1
     fi
 
     local deploy_id

package/scripts/sw-github-graphql.sh

@@ -6,8 +6,10 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="3.1.0"
+# shellcheck disable=SC2034
+VERSION="3.3.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC2034
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 # ─── Cross-platform compatibility ──────────────────────────────────────────
@@ -29,12 +31,14 @@ fi
 if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
   emit_event() {
     local event_type="$1"; shift; mkdir -p "${HOME}/.shipwright"
-    local payload="{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"type\":\"$event_type\""
+    local payload
+    payload="{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"type\":\"$event_type\""
     while [[ $# -gt 0 ]]; do local key="${1%%=*}" val="${1#*=}"; payload="${payload},\"${key}\":\"${val}\""; shift; done
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
   }
 fi
 # ─── Structured Event Log ──────────────────────────────────────────────────
+# shellcheck disable=SC2034
 EVENTS_FILE="${HOME}/.shipwright/events.jsonl"
 
 # ─── Cache Configuration ───────────────────────────────────────────────────
@@ -116,7 +120,9 @@ _gh_cache_stats() {
     _gh_cache_init
     local count=0
     local total_size=0
+    # shellcheck disable=SC2034
     local oldest=""
+    # shellcheck disable=SC2034
     local newest=""
 
     for f in "$GH_CACHE_DIR"/*.json; do
@@ -257,7 +263,8 @@ gh_file_change_frequency() {
         since=$(date -u -d "${days} days ago" +"%Y-%m-%dT%H:%M:%SZ")
     fi
 
-    local cache_key="freq_${owner}_${repo}_$(echo "$path" | tr '/' '_')_${days}d"
+    local cache_key
+    cache_key="freq_${owner}_${repo}_$(echo "$path" | tr '/' '_')_${days}d"
 
     local query='query($owner: String!, $repo: String!, $since: GitTimestamp!) {
   repository(owner: $owner, name: $repo) {
@@ -301,7 +308,8 @@ gh_blame_data() {
         return 0
     fi
 
-    local cache_key="blame_${owner}_${repo}_$(echo "$path" | tr '/' '_')"
+    local cache_key
+    cache_key="blame_${owner}_${repo}_$(echo "$path" | tr '/' '_')"
     local cached
     cached=$(_gh_cache_get "$cache_key" "14400" 2>/dev/null) && {
         emit_event "github.cache_hit" "key=$cache_key"
@@ -386,7 +394,8 @@ gh_similar_issues() {
     fi
 
     local search_query="repo:${owner}/${repo} is:issue is:closed ${search_text}"
-    local cache_key="similar_${owner}_${repo}_$(echo "$search_text" | tr ' /' '__' | head -c 50)"
+    local cache_key
+    cache_key="similar_${owner}_${repo}_$(echo "$search_text" | tr ' /' '__' | head -c 50)"
 
     local query='query($q: String!, $limit: Int!) {
   search(query: $q, type: ISSUE, first: $limit) {
@@ -436,7 +445,8 @@ gh_commit_history() {
         return 0
     fi
 
-    local cache_key="history_${owner}_${repo}_$(echo "$path" | tr '/' '_')_${limit}"
+    local cache_key
+    cache_key="history_${owner}_${repo}_$(echo "$path" | tr '/' '_')_${limit}"
     local cached
     cached=$(_gh_cache_get "$cache_key" "3600" 2>/dev/null) && {
         emit_event "github.cache_hit" "key=$cache_key"
@@ -701,7 +711,8 @@ gh_actions_runs() {
         return 0
     fi
 
-    local cache_key="actions_${owner}_${repo}_$(echo "$workflow" | tr '/' '_')_${limit}"
+    local cache_key
+    cache_key="actions_${owner}_${repo}_$(echo "$workflow" | tr '/' '_')_${limit}"
     local cached
     cached=$(_gh_cache_get "$cache_key" "900" 2>/dev/null) && {
         emit_event "github.cache_hit" "key=$cache_key"

package/scripts/sw-guild.sh

@@ -6,7 +6,8 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="3.1.0"
+# shellcheck disable=SC2034
+VERSION="3.3.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # ─── Cross-platform compatibility ──────────────────────────────────────────
@@ -28,6 +29,7 @@ fi
 if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
   emit_event() {
     local event_type="$1"; shift; mkdir -p "${HOME}/.shipwright"
+    # shellcheck disable=SC2155
     local payload="{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"type\":\"$event_type\""
     while [[ $# -gt 0 ]]; do local key="${1%%=*}" val="${1#*=}"; payload="${payload},\"${key}\":\"${val}\""; shift; done
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
@@ -39,6 +41,7 @@ GUILD_CONFIG="${GUILD_ROOT}/config.json"
 GUILD_DATA="${GUILD_ROOT}/guilds.json"
 
 # ─── Event Logging ────────────────────────────────────────────────────────
+# shellcheck disable=SC2034
 EVENTS_FILE="${HOME}/.shipwright/events.jsonl"
 
 # ─── Initialization ────────────────────────────────────────────────────────
@@ -311,6 +314,7 @@ cmd_learn() {
 # ─── Inject Knowledge into Prompt ────────────────────────────────────────
 cmd_inject() {
     local task_type="${1:-}"
+    # shellcheck disable=SC2034
     local context="${2:-}"
 
     if [[ -z "$task_type" ]]; then

package/scripts/sw-heartbeat.sh

@@ -4,39 +4,14 @@
 # ║  Write · Check · List · Clear heartbeats for autonomous agents          ║
 # ╚═══════════════════════════════════════════════════════════════════════════╝
 set -euo pipefail
-trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="3.1.0"
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# ─── Cross-platform compatibility ──────────────────────────────────────────
-# shellcheck source=lib/compat.sh
-[[ -f "$SCRIPT_DIR/lib/compat.sh" ]] && source "$SCRIPT_DIR/lib/compat.sh"
-
-# Canonical helpers (colors, output, events)
-# shellcheck source=lib/helpers.sh
-[[ -f "$SCRIPT_DIR/lib/helpers.sh" ]] && source "$SCRIPT_DIR/lib/helpers.sh"
+VERSION="3.3.0"
+# shellcheck source=lib/bootstrap.sh
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/bootstrap.sh"
 
 # SQLite persistence (DB as primary read path)
 # shellcheck source=sw-db.sh
 [[ -f "$SCRIPT_DIR/sw-db.sh" ]] && source "$SCRIPT_DIR/sw-db.sh"
-# Fallbacks when helpers not loaded (e.g. test env with overridden SCRIPT_DIR)
-[[ "$(type -t info 2>/dev/null)" == "function" ]]    || info()    { echo -e "\033[38;2;0;212;255m\033[1m▸\033[0m $*"; }
-[[ "$(type -t success 2>/dev/null)" == "function" ]] || success() { echo -e "\033[38;2;74;222;128m\033[1m✓\033[0m $*"; }
-[[ "$(type -t warn 2>/dev/null)" == "function" ]]    || warn()    { echo -e "\033[38;2;250;204;21m\033[1m⚠\033[0m $*"; }
-[[ "$(type -t error 2>/dev/null)" == "function" ]]   || error()   { echo -e "\033[38;2;248;113;113m\033[1m✗\033[0m $*" >&2; }
-if [[ "$(type -t now_iso 2>/dev/null)" != "function" ]]; then
-  now_iso()   { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
-  now_epoch() { date +%s; }
-fi
-if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
-  emit_event() {
-    local event_type="$1"; shift; mkdir -p "${HOME}/.shipwright"
-    local payload="{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"type\":\"$event_type\""
-    while [[ $# -gt 0 ]]; do local key="${1%%=*}" val="${1#*=}"; payload="${payload},\"${key}\":\"${val}\""; shift; done
-    echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
-  }
-fi
 # ─── Constants ──────────────────────────────────────────────────────────────
 HEARTBEAT_DIR="$HOME/.shipwright/heartbeats"
 
@@ -136,7 +111,7 @@ cmd_write() {
     ensure_dir
 
     local tmp_file
-    tmp_file="$(mktemp "${HEARTBEAT_DIR}/.tmp.XXXXXX")"
+    tmp_file="$(mktemp "${HEARTBEAT_DIR}/.tmp.XXXXXX")" || { error "mktemp failed for heartbeat"; return 1; }
 
     # Build JSON with jq for proper escaping
     jq -n \
@@ -160,7 +135,7 @@ cmd_write() {
         }' > "$tmp_file" || { rm -f "$tmp_file"; return 1; }
 
     # Atomic write
-    mv "$tmp_file" "${HEARTBEAT_DIR}/${job_id}.json"
+    mv "$tmp_file" "${HEARTBEAT_DIR}/${job_id}.json" || { rm -f "$tmp_file"; return 1; }
 
     # Dual-write to DB when available
     if type db_record_heartbeat >/dev/null 2>&1 && db_available 2>/dev/null; then

package/scripts/sw-hello.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  sw-hello.sh — Hello World Command                                       ║
+# ║                                                                          ║
+# ║  A simple hello world command that demonstrates the CLI structure.       ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+# shellcheck disable=SC2034
+VERSION="3.3.0"
+set -euo pipefail
+trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Canonical helpers (colors, output, events)
+# shellcheck source=lib/helpers.sh
+[[ -f "$SCRIPT_DIR/lib/helpers.sh" ]] && source "$SCRIPT_DIR/lib/helpers.sh"
+# Fallbacks when helpers not loaded (e.g. test env with overridden SCRIPT_DIR)
+[[ "$(type -t info 2>/dev/null)" == "function" ]]    || info()    { echo -e "\033[38;2;0;212;255m\033[1m▸\033[0m $*"; }
+[[ "$(type -t success 2>/dev/null)" == "function" ]] || success() { echo -e "\033[38;2;74;222;128m\033[1m✓\033[0m $*"; }
+[[ "$(type -t warn 2>/dev/null)" == "function" ]]    || warn()    { echo -e "\033[38;2;250;204;21m\033[1m⚠\033[0m $*"; }
+[[ "$(type -t error 2>/dev/null)" == "function" ]]   || error()   { echo -e "\033[38;2;248;113;113m\033[1m✗\033[0m $*" >&2; }
+
+# ─── Help text ──────────────────────────────────────────────────────────────
+show_help() {
+    cat <<EOF
+USAGE
+  shipwright hello [OPTIONS]
+
+DESCRIPTION
+  A simple hello world command.
+
+OPTIONS
+  --help, -h      Show this help text
+  --version, -v   Show version
+
+EXAMPLES
+  shipwright hello                 Print "hello world"
+  shipwright hello --help          Show this help text
+
+EOF
+}
+
+# ─── Main ───────────────────────────────────────────────────────────────────
+main() {
+    case "${1:-}" in
+        --help|-h)
+            show_help
+            exit 0
+            ;;
+        --version|-v)
+            echo "$VERSION"
+            exit 0
+            ;;
+        "")
+            # No arguments: output hello world
+            echo "hello world"
+            exit 0
+            ;;
+        *)
+            error "Unknown option: $1"
+            show_help
+            exit 1
+            ;;
+    esac
+}
+
+main "$@"

package/scripts/sw-hygiene.sh

@@ -6,7 +6,7 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="3.1.0"
+VERSION="3.3.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
@@ -27,6 +27,7 @@ if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
   emit_event() {
     local event_type="$1"; shift
     mkdir -p "${HOME}/.shipwright"
+    # shellcheck disable=SC2155
     local payload="{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"type\":\"$event_type\""
     while [[ $# -gt 0 ]]; do local key="${1%%=*}" val="${1#*=}"; payload="${payload},\"${key}\":\"${val}\""; shift; done
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
@@ -103,7 +104,8 @@ detect_dead_code() {
 
             # Check if function is used in other files (count lines with this function name)
             local usage_count
-            usage_count=$(grep -r "$func" "$REPO_DIR/scripts" --include="*.sh" 2>/dev/null | wc -l) || usage_count="0"
+            usage_count=$(grep -r "$func" "$REPO_DIR/scripts" --include="*.sh" 2>/dev/null | wc -l || true)
+            usage_count="${usage_count:-0}"
             usage_count=$(printf '%s' "$usage_count" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
 
             # Function definition counts as 1 usage; if only 1, it's unused
@@ -319,6 +321,7 @@ list_stale_branches() {
 
     # Find branches not updated in 30 days
     local old_branches
+    # shellcheck disable=SC2046
     old_branches=$(git branch -r --format="%(refname:short)%09%(committerdate:short)" 2>/dev/null | \
         awk -v cutoff=$(date -d "30 days ago" +%Y-%m-%d 2>/dev/null || date -v-30d +%Y-%m-%d) \
         '$2 < cutoff {print $1}' || true)
@@ -341,10 +344,12 @@ list_stale_branches() {
 analyze_size() {
     info "Analyzing repository size..."
 
+    # shellcheck disable=SC2034
     local total_size=0
 
     # Find large files
     info "Largest files:"
+    # shellcheck disable=SC2038
     find "$REPO_DIR" -type f ! -path '*/.git/*' ! -path '*/node_modules/*' 2>/dev/null | \
         xargs ls -lh 2>/dev/null | \
         awk '{print $5, $9}' | \
@@ -403,6 +408,7 @@ scan_platform_refactor() {
     grep -rnE "hardcoded|Hardcoded|Fallback:|fallback:|TODO|FIXME|HACK|KLUDGE" "$scripts_dir" --include="*.sh" 2>/dev/null > "$findings_raw" || true
     while IFS= read -r line; do
         [[ -z "$line" ]] && continue
+        # shellcheck disable=SC2318
         local f="${line%%:*}" rest="${line#*:}" ln="${rest%%:*}"
         ln="${ln:-0}"
         printf '{"file":"%s","line":%s}\n' "${f#$REPO_DIR/}" "$ln"
@@ -417,7 +423,8 @@ scan_platform_refactor() {
     sizes_file=$(mktemp)
     find "$scripts_dir" -maxdepth 1 -name "*.sh" -type f 2>/dev/null | while read -r f; do
         local lines
-        lines=$(wc -l < "$f" 2>/dev/null || echo 0)
+        lines=$(wc -l < "$f" 2>/dev/null || true)
+        lines="${lines:-0}"
         printf '{"script":"%s","lines":%s}\n' "$(basename "$f")" "$lines"
     done | jq -s 'sort_by(-.lines) | .[0:15]' 2>/dev/null > "$sizes_file"
     local script_sizes