forge-workflow 0.0.5 → 0.0.6

package/scripts/forge-team/index.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# forge-team — Team orchestration plugin for Forge.
+#
+# Subcommands:
+#   workload    Show team workload by developer
+#   epic        Epic progress rollup
+#   dashboard   Team health dashboard
+#   add         Add developer to team map
+#   verify      Check 1:1 Beads<>GitHub enforcement
+#   sync        Manual GitHub<>Beads sync
+#   claim       Claim an issue with pre-check
+#   help        Show usage
+#
+# Exit codes: 0=success, 1=error, 2=validation error
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source libs (graceful if missing — stubs used in early dev)
+[[ -f "$SCRIPT_DIR/lib/agent-prompt.sh" ]] && source "$SCRIPT_DIR/lib/agent-prompt.sh"
+[[ -f "$SCRIPT_DIR/lib/identity.sh" ]] && source "$SCRIPT_DIR/lib/identity.sh"
+[[ -f "$SCRIPT_DIR/lib/workload.sh" ]] && source "$SCRIPT_DIR/lib/workload.sh"
+[[ -f "$SCRIPT_DIR/lib/epic.sh" ]] && source "$SCRIPT_DIR/lib/epic.sh"
+[[ -f "$SCRIPT_DIR/lib/dashboard.sh" ]] && source "$SCRIPT_DIR/lib/dashboard.sh"
+[[ -f "$SCRIPT_DIR/lib/hooks.sh" ]] && source "$SCRIPT_DIR/lib/hooks.sh"
+[[ -f "$SCRIPT_DIR/lib/verify.sh" ]] && source "$SCRIPT_DIR/lib/verify.sh"
+[[ -f "$SCRIPT_DIR/lib/claim.sh" ]] && source "$SCRIPT_DIR/lib/claim.sh"
+
+# Source shared forge utilities
+FORGE_SCRIPTS="$(cd "$SCRIPT_DIR/.." && pwd)"
+[[ -f "$FORGE_SCRIPTS/lib/sanitize.sh" ]] && source "$FORGE_SCRIPTS/lib/sanitize.sh"
+
+# ── Stub implementations ──
+# cmd_workload provided by lib/workload.sh
+# cmd_epic provided by lib/epic.sh
+# cmd_dashboard provided by lib/dashboard.sh
+cmd_add() { auto_detect_identity "$@"; }
+# cmd_verify provided by lib/verify.sh
+cmd_sync() { forge_team_sync "$@"; }
+cmd_claim() { forge_team_claim "$@"; }
+
+cmd_help() {
+  cat <<'EOF'
+Usage: forge team <subcommand> [args...]
+
+Subcommands:
+  workload [--developer=<user>] [--me]  Show team workload
+  epic <issue-id>                        Epic progress rollup
+  dashboard                              Team health dashboard
+  add [--github=<user>]                  Add developer to team map
+  verify                                 Check 1:1 Beads<>GitHub sync
+  sync                                   Manual GitHub<>Beads sync
+  claim <issue-id> [--force]             Claim issue with pre-check
+  help                                   Show this message
+EOF
+}
+
+# ── Main dispatcher ──
+main() {
+  if [[ $# -lt 1 ]]; then
+    cmd_help >&2
+    exit 1
+  fi
+
+  local subcommand="$1"
+  shift
+
+  case "$subcommand" in
+    workload)   cmd_workload "$@" ;;
+    epic)       cmd_epic "$@" ;;
+    dashboard)  cmd_dashboard "$@" ;;
+    add)        cmd_add "$@" ;;
+    verify)     cmd_verify "$@" ;;
+    sync)       cmd_sync "$@" ;;
+    claim)      cmd_claim "$@" ;;
+    help)       cmd_help ;;
+    *)
+      echo "Error: unknown subcommand '$subcommand'" >&2
+      cmd_help >&2
+      exit 1
+      ;;
+  esac
+}
+
+main "$@"

package/scripts/forge-team/lib/agent-prompt.sh

@@ -0,0 +1,52 @@
+# agent-prompt.sh — Shared library for structured agent communication
+# All user-facing output from `forge team` goes through these helpers.
+# Uses non-guessable prefix to prevent injection from GitHub data.
+#
+# Usage: source this file from other scripts.
+# This library does NOT set errexit/pipefail.
+
+# Guard against double-sourcing (readonly would error on second source)
+if [[ -n "${_AGENT_PROMPT_LIB_LOADED:-}" ]]; then
+  return 0 2>/dev/null || true
+fi
+_AGENT_PROMPT_LIB_LOADED=1
+
+readonly FORGE_AGENT_PREFIX="FORGE_AGENT_7f3a"
+
+# Output a prompt for the AI agent to ask the user.
+# Format: FORGE_AGENT_7f3a:PROMPT: <message> (to stderr)
+agent_prompt() {
+  echo "${FORGE_AGENT_PREFIX}:PROMPT: $1" >&2
+}
+
+# Informational output.
+# Format: FORGE_AGENT_7f3a:INFO: <message> (to stderr)
+agent_info() {
+  echo "${FORGE_AGENT_PREFIX}:INFO: $1" >&2
+}
+
+# Error output.
+# Format: FORGE_AGENT_7f3a:ERROR: <message> (to stderr)
+agent_error() {
+  echo "${FORGE_AGENT_PREFIX}:ERROR: $1" >&2
+}
+
+# Strip any occurrence of the FORGE_AGENT_7f3a: prefix from input strings.
+# Prevents injection from GitHub issue titles or other external data.
+# Takes input via stdin or as $1 arg, outputs sanitized text to stdout.
+sanitize_for_agent() {
+  local input
+  if [[ $# -gt 0 ]]; then
+    input="$1"
+  else
+    input="$(cat)"
+  fi
+  # Loop until no more prefix occurrences (prevents split-prefix bypass)
+  local prev
+  while true; do
+    prev="$input"
+    input="${input//${FORGE_AGENT_PREFIX}:/}"
+    [[ "$input" == "$prev" ]] && break
+  done
+  printf '%s' "$input"
+}

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
+}