forge-workflow 0.0.4 → 0.0.6

package/scripts/forge-team/lib/claim.sh

@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+# scripts/forge-team/lib/claim.sh — Claim locking with pre-claim check
+#
+# Before allowing issue claim, checks GitHub assignee and uses flock/mkdir
+# to prevent race conditions between concurrent agents.
+#
+# Functions:
+#   pre_claim_check   — Check if issue is claimable
+#   claim_with_lock   — Atomic claim with file locking
+#   forge_team_claim  — Top-level dispatcher entry point
+#
+# Env overrides (for testing):
+#   GH_CMD   — Path to gh binary
+#   BD_CMD   — Path to bd binary
+#
+# This file does NOT set errexit/pipefail — callers manage their own shell options.
+
+# Guard against double-sourcing
+if [[ -n "${_CLAIM_LIB_LOADED:-}" ]]; then
+  return 0 2>/dev/null || true
+fi
+_CLAIM_LIB_LOADED=1
+
+_CLAIM_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source dependencies
+if [[ -f "$_CLAIM_DIR/agent-prompt.sh" ]]; then
+  source "$_CLAIM_DIR/agent-prompt.sh"
+fi
+
+if [[ -f "$_CLAIM_DIR/identity.sh" ]]; then
+  source "$_CLAIM_DIR/identity.sh"
+fi
+
+# ── Internal helpers ─────────────────────────────────────────────────────
+
+# _claim_error <message>
+_claim_error() {
+  if declare -f agent_error &>/dev/null; then
+    agent_error "$1"
+  else
+    echo "ERROR: $1" >&2
+  fi
+}
+
+# _claim_info <message>
+_claim_info() {
+  if declare -f agent_info &>/dev/null; then
+    agent_info "$1"
+  else
+    echo "INFO: $1" >&2
+  fi
+}
+
+# _claim_prompt <message>
+_claim_prompt() {
+  if declare -f agent_prompt &>/dev/null; then
+    agent_prompt "$1"
+  else
+    echo "PROMPT: $1" >&2
+  fi
+}
+
+# _get_github_issue_number <beads-id>
+# Extracts github_issue:N from bd show output. Returns number or empty.
+_get_github_issue_number() {
+  local beads_id="$1"
+  local bd_cmd="${BD_CMD:-bd}"
+  local bd_output
+  bd_output="$("$bd_cmd" show "$beads_id" 2>/dev/null)" || return 1
+
+  local issue_num
+  issue_num="$(printf '%s' "$bd_output" | grep -oP 'github_issue:\K[0-9]+' || true)"
+  if [[ -z "$issue_num" ]]; then
+    return 1
+  fi
+  printf '%s' "$issue_num"
+}
+
+# _get_github_assignee <issue-number>
+# Returns the GitHub login of the assignee, or empty if unassigned.
+_get_github_assignee() {
+  local issue_num="$1"
+  local gh_cmd="${GH_CMD:-gh}"
+  local assignee
+  assignee="$("$gh_cmd" issue view "$issue_num" --json assignees --jq '.assignees[0].login // empty' 2>/dev/null)" || return 1
+  printf '%s' "$assignee"
+}
+
+# _claim_lock_dir — Returns the path to the claim lock directory
+_claim_lock_dir() {
+  local root="${TEAM_MAP_ROOT:-.}"
+  printf '%s' "$root/.beads"
+}
+
+# ── Public API ───────────────────────────────────────────────────────────
+
+# pre_claim_check <beads-id>
+# Checks if issue is claimable. Returns 0 if clear, 1 if blocked.
+pre_claim_check() {
+  local beads_id="${1:-}"
+  if [[ -z "$beads_id" ]]; then
+    _claim_error "Usage: pre_claim_check <beads-id>"
+    return 1
+  fi
+
+  # Get current user first (validates gh auth)
+  local current_user
+  if ! current_user="$(get_github_user)"; then
+    _claim_error "GitHub CLI not authenticated. Run 'gh auth login' first."
+    return 1
+  fi
+
+  # Get GitHub issue number from beads
+  local issue_num
+  if ! issue_num="$(_get_github_issue_number "$beads_id")"; then
+    _claim_error "No github_issue number found for $beads_id"
+    return 1
+  fi
+
+  if [[ -z "$issue_num" ]]; then
+    _claim_error "No github_issue number found for $beads_id"
+    return 1
+  fi
+
+  # Query GitHub assignee
+  local assignee
+  assignee="$(_get_github_assignee "$issue_num")" || true
+
+  # If unassigned or assigned to current user: proceed
+  if [[ -z "$assignee" ]] || [[ "$assignee" == "$current_user" ]]; then
+    return 0
+  fi
+
+  # Assigned to someone else: prompt
+  _claim_prompt "$beads_id is claimed by $assignee. Override? Run: forge team claim $beads_id --force"
+  return 1
+}
+
+# claim_with_lock <beads-id> [--force]
+# Atomic claim using flock/mkdir locking pattern.
+# With --force, skips the re-check of assignee inside the lock.
+claim_with_lock() {
+  local beads_id="${1:-}"
+  local force="${2:-}"
+  if [[ -z "$beads_id" ]]; then
+    _claim_error "Usage: claim_with_lock <beads-id>"
+    return 1
+  fi
+
+  local gh_cmd="${GH_CMD:-gh}"
+  local bd_cmd="${BD_CMD:-bd}"
+  local lock_dir
+  lock_dir="$(_claim_lock_dir)"
+  mkdir -p "$lock_dir"
+
+  local lock_file="$lock_dir/claim.lock"
+
+  # Get current user
+  local current_user
+  if ! current_user="$(get_github_user)"; then
+    _claim_error "GitHub CLI not authenticated."
+    return 1
+  fi
+
+  # Get GitHub issue number
+  local issue_num
+  if ! issue_num="$(_get_github_issue_number "$beads_id")"; then
+    _claim_error "No github_issue number found for $beads_id"
+    return 1
+  fi
+
+  if command -v flock &>/dev/null; then
+    # flock-based locking
+    (
+      flock -w 5 200 || {
+        _claim_error "Claim lock timeout after 5s"
+        exit 1
+      }
+      # Re-check assignee inside lock (skip if --force)
+      if [[ "$force" != "--force" ]]; then
+        local assignee
+        assignee="$(_get_github_assignee "$issue_num")" || true
+        if [[ -n "$assignee" ]] && [[ "$assignee" != "$current_user" ]]; then
+          _claim_error "$beads_id was claimed by $assignee while waiting for lock"
+          exit 1
+        fi
+      fi
+      # Claim on both Beads and GitHub
+      "$bd_cmd" update "$beads_id" --claim >/dev/null 2>&1 || true
+      "$gh_cmd" issue edit "$issue_num" --add-assignee "$current_user" >/dev/null 2>&1 || true
+    ) 200>"$lock_file"
+    local subshell_rc=$?
+    [[ $subshell_rc -ne 0 ]] && return $subshell_rc
+  else
+    # mkdir-based fallback
+    local lock_mkdir="$lock_dir/claim.lock.d"
+    local attempts=0
+    while ! mkdir "$lock_mkdir" 2>/dev/null; do
+      attempts=$((attempts + 1))
+      if [[ $attempts -ge 50 ]]; then
+        _claim_error "Claim lock timeout after 5s"
+        return 1
+      fi
+      sleep 0.1
+    done
+    trap 'rmdir "$lock_mkdir" 2>/dev/null; trap - RETURN' RETURN
+
+    # Re-check assignee inside lock (skip if --force)
+    if [[ "$force" != "--force" ]]; then
+      local assignee
+      assignee="$(_get_github_assignee "$issue_num")" || true
+      if [[ -n "$assignee" ]] && [[ "$assignee" != "$current_user" ]]; then
+        _claim_error "$beads_id was claimed by $assignee while waiting for lock"
+        return 1
+      fi
+    fi
+    # Claim on both Beads and GitHub
+    "$bd_cmd" update "$beads_id" --claim >/dev/null 2>&1 || true
+    "$gh_cmd" issue edit "$issue_num" --add-assignee "$current_user" >/dev/null 2>&1 || true
+  fi
+
+  return 0
+}
+
+# forge_team_claim <beads-id> [--force]
+# Top-level function called by the dispatcher.
+forge_team_claim() {
+  local beads_id="${1:-}"
+  local force_flag="${2:-}"
+
+  if [[ -z "$beads_id" ]]; then
+    _claim_error "Usage: forge team claim <beads-id> [--force]"
+    return 1
+  fi
+
+  local bd_cmd="${BD_CMD:-bd}"
+
+  if [[ "$force_flag" == "--force" ]]; then
+    # Skip pre-claim check, claim directly (pass --force to skip lock re-check too)
+    claim_with_lock "$beads_id" "--force" || return 1
+    # Log override via bd comments
+    "$bd_cmd" comments add "$beads_id" "Force-claimed by $(get_github_user 2>/dev/null || echo 'unknown')" >/dev/null 2>&1 || true
+    _claim_info "$beads_id force-claimed successfully"
+    return 0
+  fi
+
+  # Normal flow: pre-claim check then lock-claim
+  if ! pre_claim_check "$beads_id"; then
+    return 1
+  fi
+
+  claim_with_lock "$beads_id" || return 1
+  _claim_info "$beads_id claimed successfully"
+  return 0
+}

package/scripts/forge-team/lib/dashboard.sh

@@ -0,0 +1,341 @@
+#!/usr/bin/env bash
+# dashboard.sh — Team health dashboard for forge-team.
+#
+# Provides cmd_dashboard [--format=json] which aggregates team issue data
+# from Beads and displays per-developer stats, stale assignments, and
+# blocked issues.
+
+# ── Dependencies ─────────────────────────────────────────────────────────
+# BD_CMD — path to bd binary (default: bd)
+BD_CMD="${BD_CMD:-bd}"
+
+# FORGE_NOW — override current epoch for testing (default: real time)
+_now() {
+  if [[ -n "${FORGE_NOW:-}" ]]; then
+    echo "$FORGE_NOW"
+  else
+    date +%s
+  fi
+}
+
+# Convert ISO8601 timestamp to epoch seconds
+_iso_to_epoch() {
+  local ts="$1"
+  # Remove trailing Z and replace T with space for date parsing
+  local clean="${ts%Z}"
+  clean="${clean//T/ }"
+  # Use date -d for GNU date (Linux/Git Bash)
+  if date -d "$clean UTC" +%s 2>/dev/null; then
+    return
+  fi
+  # Fallback: manual parse YYYY-MM-DD HH:MM:SS
+  # This handles the common case in Git Bash on Windows
+  local year month day hour min sec
+  IFS='-: ' read -r year month day hour min sec <<< "$clean"
+  # Use python if available
+  if command -v python3 &>/dev/null; then
+    python3 -c "import calendar,datetime; print(int(calendar.timegm(datetime.datetime($year,$month,$day,$hour,$min,$sec).timetuple())))"
+  elif command -v python &>/dev/null; then
+    python -c "import calendar,datetime; print(int(calendar.timegm(datetime.datetime($year,$month,$day,$hour,$min,$sec).timetuple())))"
+  else
+    # Last resort: approximate with GNU date
+    echo 0
+  fi
+}
+
+# ── Data Collection ──────────────────────────────────────────────────────
+
+# Parse bd list output into issue IDs and titles.
+# Each line: "◐ forge-aaa · Feature A" or "○ forge-bbb · Feature B"
+_parse_issue_list() {
+  local line
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    # Extract issue ID: between status icon and " · "
+    local id title
+    id="$(echo "$line" | sed -E 's/^[^ ]+ +([^ ]+) +·.*/\1/')"
+    title="$(echo "$line" | sed -E 's/^[^ ]+ +[^ ]+ +· +(.*)/\1/')"
+    echo "$id|$title"
+  done
+}
+
+# Get issue details: status, owner, updated timestamp, blocked-by list
+# Output: id|title|status|owner|updated_epoch|blocked_by
+_get_issue_details() {
+  local issue_id="$1"
+  local show_output
+  show_output="$($BD_CMD show "$issue_id" 2>/dev/null)" || return 1
+
+  local status="OPEN" owner="" updated="" blocked_by="" title=""
+
+  local line
+  local in_depends=0
+  while IFS= read -r line; do
+    # First line has status: "◐ forge-aaa · Feature A [● P2 · IN_PROGRESS]"
+    if [[ "$line" =~ \[.*·[[:space:]]*(OPEN|IN_PROGRESS|BLOCKED)\] ]]; then
+      status="${BASH_REMATCH[1]}"
+      # Extract title from first line
+      title="$(echo "$line" | sed -E 's/^[^ ]+ +[^ ]+ +· +(.+) +\[.*/\1/')"
+    fi
+
+    # Owner line
+    if [[ "$line" =~ ^Owner:[[:space:]]*(.+) ]]; then
+      owner="${BASH_REMATCH[1]}"
+    fi
+
+    # Updated line
+    if [[ "$line" =~ ^Updated:[[:space:]]*(.+) ]]; then
+      updated="${BASH_REMATCH[1]}"
+    fi
+
+    # DEPENDS ON section
+    if [[ "$line" == "DEPENDS ON" ]]; then
+      in_depends=1
+      continue
+    fi
+
+    if [[ $in_depends -eq 1 && "$line" =~ →.*([a-z]+-[a-z]+):.* ]]; then
+      # Extract dependency issue ID
+      local dep_id
+      dep_id="$(echo "$line" | sed -E 's/.*→ +[^ ]+ +([a-z]+-[a-z0-9]+):.*/\1/')"
+      if [[ -n "$blocked_by" ]]; then
+        blocked_by="$blocked_by,$dep_id"
+      else
+        blocked_by="$dep_id"
+      fi
+    fi
+  done <<< "$show_output"
+
+  local updated_epoch=0
+  if [[ -n "$updated" ]]; then
+    updated_epoch="$(_iso_to_epoch "$updated")"
+  fi
+
+  echo "$issue_id|$title|$status|$owner|$updated_epoch|$blocked_by"
+}
+
+# ── Dashboard Command ────────────────────────────────────────────────────
+
+cmd_dashboard() {
+  local format="text"
+
+  # Parse args
+  local arg
+  for arg in "$@"; do
+    case "$arg" in
+      --format=json) format="json" ;;
+      --format=*) echo "Error: unsupported format '${arg#--format=}'" >&2; return 1 ;;
+    esac
+  done
+
+  # 1. Get all open/in_progress issues
+  local issue_list
+  issue_list="$($BD_CMD list --status=open,in_progress 2>/dev/null)" || issue_list=""
+
+  # Check for empty
+  if [[ -z "$issue_list" ]]; then
+    if [[ "$format" == "json" ]]; then
+      echo '{"developers":{},"total":0,"stale":[],"blocked":[],"message":"No active issues — team is clear"}'
+    else
+      echo "No active issues — team is clear"
+    fi
+    return 0
+  fi
+
+  # 2. Parse issue IDs
+  local issues=()
+  while IFS= read -r entry; do
+    [[ -z "$entry" ]] && continue
+    issues+=("$entry")
+  done <<< "$(echo "$issue_list" | _parse_issue_list)"
+
+  # 3. Collect details for each issue
+  local now_epoch
+  now_epoch="$(_now)"
+  local stale_threshold=172800  # 48h in seconds
+
+  # Associative arrays for per-developer aggregation
+  declare -A dev_open dev_inprogress dev_blocked dev_stale
+
+  # Lists for stale and blocked sections
+  local stale_entries=()
+  local blocked_entries=()
+  local total_open=0 total_inprogress=0 total_blocked=0 total_stale=0
+
+  for entry in "${issues[@]}"; do
+    local issue_id="${entry%%|*}"
+
+    local details
+    details="$(_get_issue_details "$issue_id")" || continue
+
+    IFS='|' read -r _id _title _status _owner _updated_epoch _blocked_by <<< "$details"
+
+    # Default owner if empty
+    [[ -z "$_owner" ]] && _owner="unassigned"
+
+    # Initialize developer counters
+    [[ -z "${dev_open[$_owner]:-}" ]] && dev_open[$_owner]=0
+    [[ -z "${dev_inprogress[$_owner]:-}" ]] && dev_inprogress[$_owner]=0
+    [[ -z "${dev_blocked[$_owner]:-}" ]] && dev_blocked[$_owner]=0
+    [[ -z "${dev_stale[$_owner]:-}" ]] && dev_stale[$_owner]=0
+
+    # Count by status
+    case "$_status" in
+      OPEN)
+        dev_open[$_owner]=$(( ${dev_open[$_owner]} + 1 ))
+        total_open=$((total_open + 1))
+        ;;
+      IN_PROGRESS)
+        dev_inprogress[$_owner]=$(( ${dev_inprogress[$_owner]} + 1 ))
+        total_inprogress=$((total_inprogress + 1))
+        ;;
+      BLOCKED)
+        dev_blocked[$_owner]=$(( ${dev_blocked[$_owner]} + 1 ))
+        total_blocked=$((total_blocked + 1))
+        ;;
+    esac
+
+    # Check for blocked (has DEPENDS ON with open deps)
+    if [[ -n "$_blocked_by" ]]; then
+      dev_blocked[$_owner]=$(( ${dev_blocked[$_owner]} + 1 ))
+      total_blocked=$((total_blocked + 1))
+      blocked_entries+=("$_id|$_owner|$_title|$_blocked_by")
+    fi
+
+    # Check for stale (>48h since last update)
+    if [[ "$_updated_epoch" -gt 0 ]]; then
+      local age=$(( now_epoch - _updated_epoch ))
+      if [[ $age -gt $stale_threshold ]]; then
+        local hours=$(( age / 3600 ))
+        dev_stale[$_owner]=$(( ${dev_stale[$_owner]} + 1 ))
+        total_stale=$((total_stale + 1))
+        stale_entries+=("$_id|$_owner|$_title|${hours}h since last update")
+      fi
+    fi
+  done
+
+  local total_issues=${#issues[@]}
+
+  # 4. Output
+  if [[ "$format" == "json" ]]; then
+    _dashboard_json "$total_issues"
+  else
+    _dashboard_text "$total_issues"
+  fi
+}
+
+# ── Text Output ──────────────────────────────────────────────────────────
+
+_dashboard_text() {
+  local total_issues="$1"
+
+  echo "Team Dashboard"
+  echo "══════════════"
+  echo ""
+
+  # Header
+  printf "%-16s %4s  %11s  %7s  %5s\n" "Developer" "Open" "In Progress" "Blocked" "Stale"
+
+  # Get sorted list of developers
+  local devs=()
+  local dev
+  for dev in "${!dev_open[@]}"; do
+    devs+=("$dev")
+  done
+  # Sort developers
+  IFS=$'\n' devs=($(sort <<< "${devs[*]}")); unset IFS
+
+  for dev in "${devs[@]}"; do
+    printf "%-16s %4d  %11d  %7d  %5d\n" \
+      "$dev" \
+      "${dev_open[$dev]:-0}" \
+      "${dev_inprogress[$dev]:-0}" \
+      "${dev_blocked[$dev]:-0}" \
+      "${dev_stale[$dev]:-0}"
+  done
+
+  echo ""
+
+  # Build total summary parts
+  local parts=()
+  [[ $total_inprogress -gt 0 ]] && parts+=("$total_inprogress in progress")
+  [[ $total_blocked -gt 0 ]] && parts+=("$total_blocked blocked")
+  [[ $total_stale -gt 0 ]] && parts+=("$total_stale stale")
+  [[ $total_open -gt 0 ]] && parts+=("$total_open open")
+
+  local summary=""
+  if [[ ${#parts[@]} -gt 0 ]]; then
+    summary=" ($(IFS=', '; echo "${parts[*]}"))"
+  fi
+  echo "Total: $total_issues issues${summary}"
+
+  # Stale section
+  if [[ ${#stale_entries[@]} -gt 0 ]]; then
+    echo ""
+    echo "Stale assignments (>48h):"
+    local entry
+    for entry in "${stale_entries[@]}"; do
+      IFS='|' read -r _id _owner _title _age <<< "$entry"
+      echo "  ⚠ $_id [$_owner] — $_title ($_age)"
+    done
+  fi
+
+  # Blocked section
+  if [[ ${#blocked_entries[@]} -gt 0 ]]; then
+    echo ""
+    echo "Blocked issues:"
+    local entry
+    for entry in "${blocked_entries[@]}"; do
+      IFS='|' read -r _id _owner _title _deps <<< "$entry"
+      echo "  ⚠ $_id [$_owner] — $_title (blocked by $_deps)"
+    done
+  fi
+}
+
+# ── JSON Output ──────────────────────────────────────────────────────────
+
+_dashboard_json() {
+  local total_issues="$1"
+
+  # Build developers JSON
+  local dev_json="{"
+  local first=1
+  local devs=()
+  local dev
+  for dev in "${!dev_open[@]}"; do
+    devs+=("$dev")
+  done
+  IFS=$'\n' devs=($(sort <<< "${devs[*]}")); unset IFS
+
+  for dev in "${devs[@]}"; do
+    [[ $first -eq 0 ]] && dev_json+=","
+    first=0
+    dev_json+="\"$dev\":{\"open\":${dev_open[$dev]:-0},\"in_progress\":${dev_inprogress[$dev]:-0},\"blocked\":${dev_blocked[$dev]:-0},\"stale\":${dev_stale[$dev]:-0}}"
+  done
+  dev_json+="}"
+
+  # Build stale JSON array
+  local stale_json="["
+  first=1
+  local entry
+  for entry in "${stale_entries[@]}"; do
+    [[ $first -eq 0 ]] && stale_json+=","
+    first=0
+    IFS='|' read -r _id _owner _title _age <<< "$entry"
+    stale_json+="$(jq -n -c --arg id "$_id" --arg owner "$_owner" --arg title "$_title" --arg age "$_age" '{id:$id,owner:$owner,title:$title,age:$age}')"
+  done
+  stale_json+="]"
+
+  # Build blocked JSON array
+  local blocked_json="["
+  first=1
+  for entry in "${blocked_entries[@]}"; do
+    [[ $first -eq 0 ]] && blocked_json+=","
+    first=0
+    IFS='|' read -r _id _owner _title _deps <<< "$entry"
+    blocked_json+="$(jq -n -c --arg id "$_id" --arg owner "$_owner" --arg title "$_title" --arg deps "$_deps" '{id:$id,owner:$owner,title:$title,blocked_by:$deps}')"
+  done
+  blocked_json+="]"
+
+  echo "{\"developers\":$dev_json,\"total\":$total_issues,\"in_progress\":$total_inprogress,\"blocked\":$total_blocked,\"stale\":$total_stale,\"stale_entries\":$stale_json,\"blocked_entries\":$blocked_json}"
+}