shipwright-cli 2.4.0 → 3.1.0

package/scripts/sw-decompose.sh

@@ -6,7 +6,7 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="2.4.0"
+VERSION="3.1.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
@@ -34,16 +34,6 @@ if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
   }
 fi
-CYAN="${CYAN:-\033[38;2;0;212;255m}"
-PURPLE="${PURPLE:-\033[38;2;124;58;237m}"
-BLUE="${BLUE:-\033[38;2;0;102;255m}"
-GREEN="${GREEN:-\033[38;2;74;222;128m}"
-YELLOW="${YELLOW:-\033[38;2;250;204;21m}"
-RED="${RED:-\033[38;2;248;113;113m}"
-DIM="${DIM:-\033[2m}"
-BOLD="${BOLD:-\033[1m}"
-RESET="${RESET:-\033[0m}"
-
 # ─── Structured Event Log ──────────────────────────────────────────────────
 EVENTS_FILE="${HOME}/.shipwright/events.jsonl"
 

package/scripts/sw-deps.sh

@@ -6,7 +6,7 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="2.4.0"
+VERSION="3.1.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # ─── Cross-platform compatibility ──────────────────────────────────────────
@@ -25,24 +25,6 @@ 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
-CYAN="${CYAN:-\033[38;2;0;212;255m}"
-PURPLE="${PURPLE:-\033[38;2;124;58;237m}"
-BLUE="${BLUE:-\033[38;2;0;102;255m}"
-GREEN="${GREEN:-\033[38;2;74;222;128m}"
-YELLOW="${YELLOW:-\033[38;2;250;204;21m}"
-RED="${RED:-\033[38;2;248;113;113m}"
-DIM="${DIM:-\033[2m}"
-BOLD="${BOLD:-\033[1m}"
-RESET="${RESET:-\033[0m}"
-
 # ─── Defaults ───────────────────────────────────────────────────────────────
 DEPS_DIR="${HOME}/.shipwright/deps"
 TEST_CMD=""
@@ -174,7 +156,7 @@ cmd_classify() {
     info "Classifying PR #${pr_num}..."
 
     local pr_data
-    pr_data=$(gh pr view "$pr_num" --json number,title,author,changedFiles,isDraft --template '{{json .}}' 2>/dev/null)
+    pr_data=$(gh pr view "$pr_num" --json number,title,author,changedFiles,isDraft --template '{{json .}}' 2>/dev/null || echo "")
 
     if [[ -z "$pr_data" ]]; then
         error "PR #${pr_num} not found"
@@ -415,7 +397,7 @@ cmd_batch() {
     local approved=0
     local flagged=0
 
-    echo "$prs" | jq -r '.[] | .number' | while read -r pr_num; do
+    while read -r pr_num; do
         info "Processing PR #${pr_num}..."
 
         local classify_json
@@ -438,7 +420,7 @@ cmd_batch() {
                 ;;
         esac
         processed=$((processed + 1))
-    done
+    done < <(echo "$prs" | jq -r '.[] | .number')
 
     echo ""
     echo -e "${CYAN}${BOLD}═══ Batch Summary ═══${RESET}"
@@ -470,7 +452,7 @@ cmd_report() {
     if [[ -n "$prs" && "$prs" != "[]" ]]; then
         total=$(echo "$prs" | jq 'length')
 
-        echo "$prs" | jq -r '.[] | .title' | while read -r title; do
+        while read -r title; do
             if [[ "$title" =~ from\ ([^ ]+)\ to\ ([^ ]+) ]]; then
                 local from_ver="${BASH_REMATCH[1]}"
                 local to_ver="${BASH_REMATCH[2]}"
@@ -482,7 +464,7 @@ cmd_report() {
                     major) major_count=$((major_count + 1)) ;;
                 esac
             fi
-        done
+        done < <(echo "$prs" | jq -r '.[] | .title')
     fi
 
     # Find oldest PR
@@ -491,7 +473,15 @@ cmd_report() {
         local oldest_date
         oldest_date=$(echo "$prs" | jq -r '.[0].createdAt')
         if [[ -n "$oldest_date" && "$oldest_date" != "null" ]]; then
-            oldest_age="$(date -d "$oldest_date" '+%s' 2>/dev/null || echo '?') seconds ago"
+            local oldest_epoch
+            oldest_epoch=$(date -d "$oldest_date" '+%s' 2>/dev/null || date -jf "%Y-%m-%dT%H:%M:%SZ" "$oldest_date" '+%s' 2>/dev/null || echo "")
+            if [[ -n "$oldest_epoch" ]]; then
+                local now_e; now_e=$(date +%s)
+                local age_days=$(( (now_e - oldest_epoch) / 86400 ))
+                oldest_age="${age_days} days ago"
+            else
+                oldest_age="?"
+            fi
         fi
     fi
 

package/scripts/sw-developer-simulation.sh

@@ -6,7 +6,7 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="2.4.0"
+VERSION="3.1.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
@@ -34,16 +34,6 @@ if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
   }
 fi
-CYAN="${CYAN:-\033[38;2;0;212;255m}"
-PURPLE="${PURPLE:-\033[38;2;124;58;237m}"
-BLUE="${BLUE:-\033[38;2;0;102;255m}"
-GREEN="${GREEN:-\033[38;2;74;222;128m}"
-YELLOW="${YELLOW:-\033[38;2;250;204;21m}"
-RED="${RED:-\033[38;2;248;113;113m}"
-DIM="${DIM:-\033[2m}"
-BOLD="${BOLD:-\033[1m}"
-RESET="${RESET:-\033[0m}"
-
 # ─── Source Intelligence Core ─────────────────────────────────────────────
 if [[ -f "$SCRIPT_DIR/sw-intelligence.sh" ]]; then
     source "$SCRIPT_DIR/sw-intelligence.sh"

package/scripts/sw-discovery.sh

@@ -7,12 +7,12 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="2.4.0"
+VERSION="3.1.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 # ─── Dependency check ─────────────────────────────────────────────────────────
-if ! command -v jq &>/dev/null; then
+if ! command -v jq >/dev/null 2>&1; then
     echo "ERROR: sw-discovery.sh requires 'jq'. Install with: brew install jq (macOS) or apt install jq (Linux)" >&2
     exit 1
 fi
@@ -41,21 +41,18 @@ if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
   }
 fi
-CYAN="${CYAN:-\033[38;2;0;212;255m}"
-PURPLE="${PURPLE:-\033[38;2;124;58;237m}"
-BLUE="${BLUE:-\033[38;2;0;102;255m}"
-GREEN="${GREEN:-\033[38;2;74;222;128m}"
-YELLOW="${YELLOW:-\033[38;2;250;204;21m}"
-RED="${RED:-\033[38;2;248;113;113m}"
-DIM="${DIM:-\033[2m}"
-BOLD="${BOLD:-\033[1m}"
-RESET="${RESET:-\033[0m}"
-
 # ─── Discovery Storage ──────────────────────────────────────────────────────
 DISCOVERIES_FILE="${HOME}/.shipwright/discoveries.jsonl"
 DISCOVERIES_DIR="${HOME}/.shipwright/discoveries"
 DISCOVERY_TTL_SECS=$((24 * 60 * 60))  # 24 hours default
 
+# ─── Remote Discovery Server (optional) ─────────────────────────────────────
+# Set via env var or daemon-config.json: "discovery_server_url"
+DISCOVERY_SERVER_URL="${DISCOVERY_SERVER_URL:-}"
+if [[ -z "$DISCOVERY_SERVER_URL" && -f ".claude/daemon-config.json" ]]; then
+    DISCOVERY_SERVER_URL=$(jq -r '.discovery_server_url // ""' ".claude/daemon-config.json" 2>/dev/null || true)
+fi
+
 ensure_discoveries_dir() {
     mkdir -p "$DISCOVERIES_DIR"
 }
@@ -91,17 +88,37 @@ broadcast_discovery() {
         '{ts: $ts, ts_epoch: $ts_epoch, pipeline_id: $pipeline_id, category: $category, file_patterns: $file_patterns, discovery: $discovery, resolution: $resolution}')
 
     echo "$entry" >> "$DISCOVERIES_FILE"
-    type rotate_jsonl &>/dev/null 2>&1 && rotate_jsonl "$DISCOVERIES_FILE" 5000
+    type rotate_jsonl >/dev/null 2>&1 && rotate_jsonl "$DISCOVERIES_FILE" 5000
+
+    # Fire-and-forget POST to remote discovery server if configured
+    if [[ -n "${DISCOVERY_SERVER_URL:-}" ]]; then
+        curl -sS -X POST "${DISCOVERY_SERVER_URL}/api/discoveries" \
+            -H "Content-Type: application/json" \
+            -d "$entry" \
+            --max-time 5 >/dev/null 2>&1 &
+    fi
+
     success "Broadcast discovery: ${category} (${file_patterns})"
 }
 
 # query: find relevant discoveries for given file patterns
+# Uses path overlap + semantic similarity (Jaccard on keywords, domain expansion)
 query_discoveries() {
     local file_patterns="$1"
     local limit="${2:-10}"
 
     ensure_discoveries_dir
 
+    # Merge remote discoveries if server configured (best-effort)
+    if [[ -n "${DISCOVERY_SERVER_URL:-}" ]]; then
+        local remote_results
+        remote_results=$(curl -sS "${DISCOVERY_SERVER_URL}/api/discoveries?patterns=${file_patterns}" \
+            --max-time 5 2>/dev/null || true)
+        if [[ -n "$remote_results" ]] && echo "$remote_results" | jq -e '.' >/dev/null 2>&1; then
+            echo "$remote_results" | jq -cr '.[]' >> "$DISCOVERIES_FILE" 2>/dev/null || true
+        fi
+    fi
+
     [[ ! -f "$DISCOVERIES_FILE" ]] && {
         info "No discoveries yet"
         return 0
@@ -109,30 +126,60 @@ query_discoveries() {
 
     local count=0
     local found=false
+    local query_context
+    query_context=$(_expand_domain_keywords "$file_patterns")
 
+    # Collect candidates (path or semantic match)
+    local candidates
+    candidates=()
     while IFS= read -r line; do
         [[ -z "$line" ]] && continue
 
-        local disc_patterns
+        local disc_patterns discovery_desc
         disc_patterns=$(echo "$line" | jq -r '.file_patterns // ""' 2>/dev/null || echo "")
+        discovery_desc=$(echo "$line" | jq -r '.discovery // ""' 2>/dev/null || echo "")
 
-        # Check if patterns overlap
+        local matched=false
         if patterns_overlap "$file_patterns" "$disc_patterns"; then
-            if [[ "$found" == "false" ]]; then
-                success "Found relevant discoveries:"
-                found=true
+            matched=true
+        else
+            # Semantic match: discovery about "authentication" matches "session verification"
+            local desc_similarity
+            desc_similarity=$(_discovery_semantic_match "$query_context" "$discovery_desc")
+            if [[ "${desc_similarity:-0}" -gt 30 ]]; then
+                matched=true
             fi
+        fi
 
-            local category discovery
-            category=$(echo "$line" | jq -r '.category' 2>/dev/null || echo "?")
-            discovery=$(echo "$line" | jq -r '.discovery' 2>/dev/null || echo "?")
+        if [[ "$matched" == "true" ]]; then
+            candidates+=("$line")
+        fi
+    done < "$DISCOVERIES_FILE"
 
-            echo -e "  ${DIM}→${RESET} [${category}] ${discovery} [${disc_patterns}]"
+    # Optionally use Claude to rank when many candidates
+    if [[ "${INTELLIGENCE_ENABLED:-auto}" != "false" ]] && command -v claude &>/dev/null 2>&1 && [[ ${#candidates[@]} -gt 5 ]]; then
+        # TODO: batch Claude call to rank by relevance (future enhancement)
+        :
+    fi
 
-            ((count++))
-            [[ "$count" -ge "$limit" ]] && break
+    # Output up to limit
+    local line
+    for line in "${candidates[@]+"${candidates[@]}"}"; do
+        if [[ "$found" == "false" ]]; then
+            success "Found relevant discoveries:"
+            found=true
         fi
-    done < "$DISCOVERIES_FILE"
+
+        local category discovery disc_patterns
+        category=$(echo "$line" | jq -r '.category' 2>/dev/null || echo "?")
+        discovery=$(echo "$line" | jq -r '.discovery' 2>/dev/null || echo "?")
+        disc_patterns=$(echo "$line" | jq -r '.file_patterns // ""' 2>/dev/null || echo "")
+
+        echo -e "  ${DIM}→${RESET} [${category}] ${discovery} [${disc_patterns}]"
+
+        count=$((count + 1))
+        [[ "$count" -ge "$limit" ]] && break
+    done
 
     if [[ "$found" == "false" ]]; then
         info "No relevant discoveries found for patterns: ${file_patterns}"
@@ -153,8 +200,10 @@ inject_discoveries() {
 
     local seen_file
     seen_file=$(get_seen_file "$pipeline_id")
+    local query_context
+    query_context=$(_expand_domain_keywords "$file_patterns")
 
-    # Find relevant discoveries not yet seen
+    # Find relevant discoveries not yet seen (path or semantic match)
     local new_count=0
     local injected_entries=()
 
@@ -171,13 +220,25 @@ inject_discoveries() {
             fi
         fi
 
-        # Check if relevant to current file patterns
-        local disc_patterns
+        # Check if relevant: path overlap OR semantic similarity > 30
+        local disc_patterns discovery_desc
         disc_patterns=$(echo "$line" | jq -r '.file_patterns // ""' 2>/dev/null || echo "")
+        discovery_desc=$(echo "$line" | jq -r '.discovery // ""' 2>/dev/null || echo "")
 
+        local matched=false
         if [[ -n "$disc_patterns" ]] && patterns_overlap "$file_patterns" "$disc_patterns"; then
+            matched=true
+        else
+            local desc_similarity
+            desc_similarity=$(_discovery_semantic_match "$query_context" "$discovery_desc")
+            if [[ "${desc_similarity:-0}" -gt 30 ]]; then
+                matched=true
+            fi
+        fi
+
+        if [[ "$matched" == "true" ]]; then
             injected_entries+=("$line")
-            ((new_count++))
+            new_count=$((new_count + 1))
         fi
     done < "$DISCOVERIES_FILE"
 
@@ -227,6 +288,53 @@ inject_discoveries() {
     done
 }
 
+# ─── Semantic matching helpers ───────────────────────────────────────────────
+
+# Domain keyword expansion for related concepts
+_expand_domain_keywords() {
+    local text="$1"
+    local expanded="$text"
+
+    # Domain synonym groups (iterate over fixed keys to avoid set -u issues)
+    local dom
+    for dom in auth api db ui test deploy error perf; do
+        case "$dom" in
+            auth)   [[ "$text" =~ [aA]uth ]] && expanded="$expanded authentication authorization login session token credential permission access" ;;
+            api)    [[ "$text" =~ [aA]pi ]]  && expanded="$expanded endpoint route handler request response rest graphql" ;;
+            db)     [[ "$text" =~ [dD]b ]]   && expanded="$expanded database query migration schema model table sql" ;;
+            ui)     [[ "$text" =~ [uU]i ]]   && expanded="$expanded component view render template layout style css frontend" ;;
+            test)   [[ "$text" =~ [tT]est ]] && expanded="$expanded testing assertion coverage mock stub fixture spec" ;;
+            deploy) [[ "$text" =~ [dD]eploy ]] && expanded="$expanded deployment release publish ship ci cd pipeline" ;;
+            error)  [[ "$text" =~ [eE]rror ]] && expanded="$expanded exception failure crash bug issue defect" ;;
+            perf)   [[ "$text" =~ [pP]erf ]] && expanded="$expanded performance optimization speed latency throughput cache" ;;
+        esac
+    done
+
+    echo "$expanded"
+}
+
+# Semantic similarity between discovery descriptions (Jaccard on keywords)
+_discovery_semantic_match() {
+    local query_desc="$1"
+    local discovery_desc="$2"
+
+    # Extract keywords from both descriptions
+    local query_words discovery_words
+    query_words=$(echo "$query_desc" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '\n' | sort -u | grep -vE '^(the|a|an|is|are|was|were|in|on|at|to|for|of|and|or|but|not|with|this|that|from|by)$')
+    discovery_words=$(echo "$discovery_desc" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '\n' | sort -u | grep -vE '^(the|a|an|is|are|was|were|in|on|at|to|for|of|and|or|but|not|with|this|that|from|by)$')
+
+    # Compute Jaccard similarity
+    local intersection union
+    intersection=$(comm -12 <(echo "$query_words") <(echo "$discovery_words") 2>/dev/null | wc -l | tr -d ' ')
+    union=$(sort -u <(echo "$query_words") <(echo "$discovery_words") 2>/dev/null | wc -l | tr -d ' ')
+
+    if [[ "$union" -gt 0 ]]; then
+        echo "$((intersection * 100 / union))"
+    else
+        echo "0"
+    fi
+}
+
 # patterns_overlap: check if two comma-separated patterns overlap
 patterns_overlap() {
     local patterns1="$1"
@@ -292,7 +400,7 @@ clean_discoveries() {
         if [[ "$ts_epoch" -ge "$cutoff" ]]; then
             echo "$line" >> "$tmp_file"
         else
-            ((removed_count++))
+            removed_count=$((removed_count + 1))
         fi
     done < "$DISCOVERIES_FILE"
 

package/scripts/sw-doc-fleet.sh

@@ -6,7 +6,7 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="2.4.0"
+VERSION="3.1.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
@@ -32,16 +32,6 @@ if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
   }
 fi
-CYAN="${CYAN:-\033[38;2;0;212;255m}"
-PURPLE="${PURPLE:-\033[38;2;124;58;237m}"
-BLUE="${BLUE:-\033[38;2;0;102;255m}"
-GREEN="${GREEN:-\033[38;2;74;222;128m}"
-YELLOW="${YELLOW:-\033[38;2;250;204;21m}"
-RED="${RED:-\033[38;2;248;113;113m}"
-DIM="${DIM:-\033[2m}"
-BOLD="${BOLD:-\033[1m}"
-RESET="${RESET:-\033[0m}"
-
 # ─── Constants ──────────────────────────────────────────────────────────────
 FLEET_HOME="${HOME}/.shipwright/doc-fleet"
 FLEET_STATE="${FLEET_HOME}/state.json"
@@ -115,9 +105,9 @@ cmd_audit() {
     total_checks=$((total_checks + 1))
     if [[ -f "${REPO_DIR}/.claude/CLAUDE.md" ]]; then
         local claude_age_days=0
-        if command -v stat &>/dev/null; then
+        if command -v stat >/dev/null 2>&1; then
             local claude_mtime
-            claude_mtime=$(stat -f %m "${REPO_DIR}/.claude/CLAUDE.md" 2>/dev/null || stat -c %Y "${REPO_DIR}/.claude/CLAUDE.md" 2>/dev/null || echo "0")
+            claude_mtime=$(file_mtime "${REPO_DIR}/.claude/CLAUDE.md")
             local now_epoch_val
             now_epoch_val=$(date +%s)
             claude_age_days=$(( (now_epoch_val - claude_mtime) / 86400 ))
@@ -376,7 +366,7 @@ cmd_launch() {
         fi
 
         # Spawn via tmux if available
-        if command -v tmux &>/dev/null; then
+        if command -v tmux >/dev/null 2>&1; then
             local session_name="docfleet-${role}"
 
             # Kill existing session for this role if present
@@ -482,7 +472,7 @@ cmd_status() {
     local active=0
     for role in $FLEET_ROLES; do
         local session_name="docfleet-${role}"
-        if command -v tmux &>/dev/null && tmux has-session -t "$session_name" 2>/dev/null; then
+        if command -v tmux >/dev/null 2>&1 && tmux has-session -t "$session_name" 2>/dev/null; then
             echo -e "  ${GREEN}●${RESET} ${CYAN}${role}${RESET}  →  tmux session: ${DIM}${session_name}${RESET}"
             active=$((active + 1))
         else
@@ -529,7 +519,7 @@ cmd_retire() {
     local retired=0
     for role in $roles_to_retire; do
         local session_name="docfleet-${role}"
-        if command -v tmux &>/dev/null && tmux has-session -t "$session_name" 2>/dev/null; then
+        if command -v tmux >/dev/null 2>&1 && tmux has-session -t "$session_name" 2>/dev/null; then
             tmux kill-session -t "$session_name" 2>/dev/null && \
                 success "Retired: ${CYAN}${role}${RESET}" || \
                 warn "Failed to retire: ${role}"
@@ -566,7 +556,7 @@ cmd_manifest() {
         # Extract first heading
         title=$(grep -m1 '^#' "$md_file" 2>/dev/null | sed 's/^#* //' || echo "$rel_path")
         local mtime
-        mtime=$(stat -f %m "$md_file" 2>/dev/null || stat -c %Y "$md_file" 2>/dev/null || echo "0")
+        mtime=$(file_mtime "$md_file")
 
         # Determine audience
         local audience="contributor"

package/scripts/sw-docs-agent.sh

@@ -6,7 +6,7 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="2.4.0"
+VERSION="3.1.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
@@ -34,16 +34,6 @@ if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
   }
 fi
-CYAN="${CYAN:-\033[38;2;0;212;255m}"
-PURPLE="${PURPLE:-\033[38;2;124;58;237m}"
-BLUE="${BLUE:-\033[38;2;0;102;255m}"
-GREEN="${GREEN:-\033[38;2;74;222;128m}"
-YELLOW="${YELLOW:-\033[38;2;250;204;21m}"
-RED="${RED:-\033[38;2;248;113;113m}"
-DIM="${DIM:-\033[2m}"
-BOLD="${BOLD:-\033[1m}"
-RESET="${RESET:-\033[0m}"
-
 # ─── Documentation Agent State ────────────────────────────────────────────
 AGENT_HOME="${HOME}/.shipwright/docs-agent"
 FRESHNESS_DB="${AGENT_HOME}/freshness.json"
@@ -321,7 +311,7 @@ show_coverage() {
         script_name=$(basename "$script" .sh | sed 's/^sw-//')
 
         if grep -q "$script_name" "$REPO_DIR/.claude/CLAUDE.md" 2>/dev/null; then
-            ((documented_count++))
+            documented_count=$((documented_count + 1))
         else
             undocumented_scripts="${undocumented_scripts}${script_name}\\n"
         fi
@@ -371,7 +361,7 @@ scan_gaps() {
 
             if [[ "$freshness" -lt 70 ]]; then
                 warn "Stale section in README: $section (freshness: ${freshness}%)"
-                ((gaps_found++))
+                gaps_found=$((gaps_found + 1))
             fi
         done
     fi
@@ -387,7 +377,7 @@ scan_gaps() {
 
             if [[ "$freshness" -lt 70 ]]; then
                 warn "Stale section in CLAUDE.md: $section (freshness: ${freshness}%)"
-                ((gaps_found++))
+                gaps_found=$((gaps_found + 1))
             fi
         done
     fi
@@ -412,11 +402,11 @@ sync_docs() {
 
     # Regenerate API reference
     generate_api_reference
-    ((synced_count++))
+    synced_count=$((synced_count + 1))
 
     # Regenerate wiki
     generate_wiki_pages
-    ((synced_count++))
+    synced_count=$((synced_count + 1))
 
     success "Documentation sync complete ($synced_count updates)"
     emit_event "docs_sync_complete" "updates=$synced_count"

package/scripts/sw-docs.sh

@@ -6,7 +6,7 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="2.4.0"
+VERSION="3.1.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
@@ -19,6 +19,8 @@ REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 [[ -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 $*"; }
+# Color fallbacks when helpers not loaded
+: "${CYAN:=}" "${BOLD:=}" "${RESET:=}" "${DIM:=}" "${GREEN:=}" "${RED:=}" "${YELLOW:=}" "${PURPLE:=}" "${WHITE:=}" "${BLUE:=}"
 [[ "$(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; }
@@ -34,16 +36,6 @@ if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
   }
 fi
-CYAN="${CYAN:-\033[38;2;0;212;255m}"
-PURPLE="${PURPLE:-\033[38;2;124;58;237m}"
-BLUE="${BLUE:-\033[38;2;0;102;255m}"
-GREEN="${GREEN:-\033[38;2;74;222;128m}"
-YELLOW="${YELLOW:-\033[38;2;250;204;21m}"
-RED="${RED:-\033[38;2;248;113;113m}"
-DIM="${DIM:-\033[2m}"
-BOLD="${BOLD:-\033[1m}"
-RESET="${RESET:-\033[0m}"
-
 # ─── AUTO Section Processing ────────────────────────────────────────────────
 
 # Find all files with AUTO markers
@@ -501,7 +493,7 @@ docs_wiki() {
     fi
 
     # Push to GitHub wiki
-    if [[ "${NO_GITHUB:-}" == "true" ]] || ! command -v gh &>/dev/null; then
+    if [[ "${NO_GITHUB:-}" == "true" ]] || ! command -v gh >/dev/null 2>&1; then
         warn "GitHub not available — wiki pages saved to: $wiki_dir"
         return 0
     fi