forge-workflow 0.0.5 → 0.0.6

package/scripts/forge-team/lib/sync-github.sh

@@ -0,0 +1,317 @@
+#!/usr/bin/env bash
+# scripts/forge-team/lib/sync-github.sh — Bidirectional sync between Beads and GitHub
+#
+# Functions:
+#   sync_issue_create  <beads-id>             — Create GitHub issue from Beads
+#   sync_issue_claim   <beads-id>             — Assign current dev on GitHub
+#   sync_issue_status  <beads-id> <status>    — Update status label on GitHub
+#   sync_issue_close   <beads-id>             — Close GitHub issue
+#   sync_issue_deps    <beads-id-a> <beads-id-b> — Add "Blocked by" comment
+#   _get_github_issue_number <beads-id>       — Extract github_issue from bd show
+#
+# Env overrides (for testing):
+#   GH_CMD  — Path to gh binary (default: gh)
+#   BD_CMD  — Path to bd binary (default: bd)
+#
+# All GitHub-sourced strings are sanitized via sanitize_for_agent() before
+# use in shell commands (OWASP A03).
+#
+# This file does NOT set errexit/pipefail — callers manage their own shell options.
+
+# Guard against double-sourcing
+if [[ -n "${_SYNC_GITHUB_LIB_LOADED:-}" ]]; then
+  return 0 2>/dev/null || true
+fi
+_SYNC_GITHUB_LIB_LOADED=1
+
+_SYNC_GITHUB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libraries (graceful fallback if missing)
+# sanitize.sh — from scripts/lib/
+_SYNC_SANITIZE_PATH="$_SYNC_GITHUB_DIR/../../lib/sanitize.sh"
+if [[ -f "$_SYNC_SANITIZE_PATH" ]]; then
+  source "$_SYNC_SANITIZE_PATH"
+fi
+
+# agent-prompt.sh — from forge-team/lib/ (provides sanitize_for_agent)
+if [[ -f "$_SYNC_GITHUB_DIR/agent-prompt.sh" ]]; then
+  source "$_SYNC_GITHUB_DIR/agent-prompt.sh"
+fi
+
+# identity.sh — from forge-team/lib/ (provides get_github_user)
+if [[ -f "$_SYNC_GITHUB_DIR/identity.sh" ]]; then
+  source "$_SYNC_GITHUB_DIR/identity.sh"
+fi
+
+# ── Internal helpers ─────────────────────────────────────────────────────
+
+# _sync_error <message>
+# Output error via agent_error if available, otherwise stderr
+_sync_error() {
+  if declare -f agent_error &>/dev/null; then
+    agent_error "$1"
+  else
+    echo "ERROR: $1" >&2
+  fi
+}
+
+# _safe_sanitize <string>
+# Sanitize using both sanitize_for_agent (strip agent prefix) and sanitize
+# (strip shell injection patterns). Either or both may be available.
+_safe_sanitize() {
+  local input="${1:-}"
+  # Step 1: strip agent prefix injection if sanitize_for_agent is available
+  if declare -f sanitize_for_agent &>/dev/null; then
+    input="$(sanitize_for_agent "$input")"
+  fi
+  # Step 2: strip shell injection patterns (OWASP A03) if sanitize is available
+  if declare -f sanitize &>/dev/null; then
+    input="$(sanitize "$input")"
+  fi
+  printf '%s' "$input"
+}
+
+# ── _get_github_issue_number ─────────────────────────────────────────────
+# Extracts github_issue number from `bd show <id>` output.
+# Looks for `github_issue:N` pattern.
+# Returns the number or empty string (exit 1 if not found).
+_get_github_issue_number() {
+  local beads_id="${1:-}"
+  if [[ -z "$beads_id" ]]; then
+    _sync_error "beads-id required"
+    return 1
+  fi
+
+  local bd_cmd="${BD_CMD:-bd}"
+  local show_output
+  show_output="$("$bd_cmd" show "$beads_id" 2>/dev/null)" || {
+    _sync_error "Failed to get beads info for $beads_id"
+    return 1
+  }
+
+  local issue_num
+  issue_num="$(printf '%s' "$show_output" | grep -oP 'github_issue:\K[0-9]+' | head -1)"
+
+  if [[ -z "$issue_num" ]]; then
+    _sync_error "No github_issue found for $beads_id"
+    return 1
+  fi
+
+  printf '%s' "$issue_num"
+  return 0
+}
+
+# ── _get_issue_title ─────────────────────────────────────────────────────
+# Extracts issue title from `bd show <id>` output.
+# Looks for "Title: <text>" line or falls back to the summary line.
+_get_issue_title() {
+  local beads_id="${1:-}"
+  local bd_cmd="${BD_CMD:-bd}"
+  local show_output
+  show_output="$("$bd_cmd" show "$beads_id" 2>/dev/null)" || return 1
+
+  local title
+  # Try "Title: ..." line first
+  title="$(printf '%s' "$show_output" | grep -oP '^Title:\s*\K.*' | head -1)"
+
+  if [[ -z "$title" ]]; then
+    # Fallback: extract from summary line "○ <id> · <title> [...]"
+    title="$(printf '%s' "$show_output" | grep -oP '·\s*\K[^\[]+' | head -1 | sed 's/[[:space:]]*$//')"
+  fi
+
+  if [[ -z "$title" ]]; then
+    title="$beads_id"
+  fi
+
+  printf '%s' "$title"
+}
+
+# ── Public API ───────────────────────────────────────────────────────────
+
+# sync_issue_create <beads-id>
+# Creates GitHub issue from Beads issue data.
+# Stores GitHub issue number back via `bd set-state`.
+# Returns 0 on success, 1 on failure.
+sync_issue_create() {
+  local beads_id="${1:-}"
+  if [[ -z "$beads_id" ]]; then
+    _sync_error "beads-id required"
+    return 1
+  fi
+
+  local gh_cmd="${GH_CMD:-gh}"
+  local bd_cmd="${BD_CMD:-bd}"
+
+  # Get title from bd show
+  local raw_title
+  raw_title="$(_get_issue_title "$beads_id")" || {
+    _sync_error "Failed to get title for $beads_id"
+    return 1
+  }
+
+  # Sanitize title (OWASP A03)
+  local title
+  title="$(_safe_sanitize "$raw_title")"
+
+  # Create GitHub issue
+  local gh_output
+  gh_output="$("$gh_cmd" issue create --title "$title" --body "Beads: $beads_id" 2>/dev/null)" || {
+    _sync_error "Failed to create GitHub issue for $beads_id"
+    return 1
+  }
+
+  # Extract issue number from URL (e.g., https://github.com/.../issues/42)
+  local issue_num
+  issue_num="$(printf '%s' "$gh_output" | grep -oP '/issues/\K[0-9]+' | head -1)"
+
+  if [[ -z "$issue_num" ]]; then
+    _sync_error "Could not extract issue number from: $gh_output"
+    return 1
+  fi
+
+  # Store issue number in Beads
+  "$bd_cmd" set-state "$beads_id" "github_issue=$issue_num" >/dev/null 2>&1 || {
+    _sync_error "Failed to store github_issue=$issue_num for $beads_id"
+    return 1
+  }
+
+  # Update beads-mapping.json for verify Check 4
+  local mapping_file=".github/beads-mapping.json"
+  if [[ -f "$mapping_file" ]]; then
+    local updated
+    updated="$(jq --arg num "$issue_num" --arg id "$beads_id" '.[$num] = $id' "$mapping_file")"
+    printf '%s\n' "$updated" > "$mapping_file"
+  else
+    mkdir -p .github
+    printf '%s\n' "{\"$issue_num\":\"$beads_id\"}" > "$mapping_file"
+  fi
+
+  return 0
+}
+
+# sync_issue_claim <beads-id>
+# Assigns the current developer to the GitHub issue.
+# Returns 0 on success.
+sync_issue_claim() {
+  local beads_id="${1:-}"
+  if [[ -z "$beads_id" ]]; then
+    _sync_error "beads-id required"
+    return 1
+  fi
+
+  local gh_cmd="${GH_CMD:-gh}"
+
+  # Get GitHub issue number
+  local issue_num
+  issue_num="$(_get_github_issue_number "$beads_id")" || return 1
+
+  # Get current developer's GitHub username
+  local user
+  user="$(get_github_user)" || {
+    _sync_error "Failed to get GitHub username"
+    return 1
+  }
+
+  # Update assignee
+  "$gh_cmd" issue edit "$issue_num" --add-assignee "$user" >/dev/null 2>&1 || {
+    _sync_error "Failed to assign $user to issue #$issue_num"
+    return 1
+  }
+
+  return 0
+}
+
+# sync_issue_status <beads-id> <status>
+# Updates status label on the GitHub issue.
+# Maps: open → status/open, in_progress → status/in-progress, blocked → status/blocked
+# Returns 0 on success.
+sync_issue_status() {
+  local beads_id="${1:-}"
+  local status="${2:-}"
+  if [[ -z "$beads_id" ]] || [[ -z "$status" ]]; then
+    _sync_error "beads-id and status required"
+    return 1
+  fi
+
+  local gh_cmd="${GH_CMD:-gh}"
+
+  # Get GitHub issue number
+  local issue_num
+  issue_num="$(_get_github_issue_number "$beads_id")" || return 1
+
+  # Map status to label
+  local label
+  case "$status" in
+    open)        label="status/open" ;;
+    in_progress) label="status/in-progress" ;;
+    blocked)     label="status/blocked" ;;
+    *)
+      _sync_error "Unknown status: $status (expected: open, in_progress, blocked)"
+      return 1
+      ;;
+  esac
+
+  # Remove old status labels, add new one
+  "$gh_cmd" issue edit "$issue_num" \
+    --remove-label "status/open" \
+    --remove-label "status/in-progress" \
+    --remove-label "status/blocked" \
+    --add-label "$label" >/dev/null 2>&1 || {
+    _sync_error "Failed to update status label on issue #$issue_num"
+    return 1
+  }
+
+  return 0
+}
+
+# sync_issue_close <beads-id>
+# Closes the GitHub issue.
+# Returns 0 on success.
+sync_issue_close() {
+  local beads_id="${1:-}"
+  if [[ -z "$beads_id" ]]; then
+    _sync_error "beads-id required"
+    return 1
+  fi
+
+  local gh_cmd="${GH_CMD:-gh}"
+
+  # Get GitHub issue number
+  local issue_num
+  issue_num="$(_get_github_issue_number "$beads_id")" || return 1
+
+  # Close the issue
+  "$gh_cmd" issue close "$issue_num" >/dev/null 2>&1 || {
+    _sync_error "Failed to close issue #$issue_num"
+    return 1
+  }
+
+  return 0
+}
+
+# sync_issue_deps <beads-id-a> <beads-id-b>
+# Adds "Blocked by #N-B" comment on issue A.
+# Returns 0 on success.
+sync_issue_deps() {
+  local beads_id_a="${1:-}"
+  local beads_id_b="${2:-}"
+  if [[ -z "$beads_id_a" ]] || [[ -z "$beads_id_b" ]]; then
+    _sync_error "Two beads-ids required (A blocked by B)"
+    return 1
+  fi
+
+  local gh_cmd="${GH_CMD:-gh}"
+
+  # Get both GitHub issue numbers
+  local issue_num_a issue_num_b
+  issue_num_a="$(_get_github_issue_number "$beads_id_a")" || return 1
+  issue_num_b="$(_get_github_issue_number "$beads_id_b")" || return 1
+
+  # Add comment on A referencing B
+  "$gh_cmd" issue comment "$issue_num_a" --body "Blocked by #$issue_num_b" >/dev/null 2>&1 || {
+    _sync_error "Failed to add dependency comment on issue #$issue_num_a"
+    return 1
+  }
+
+  return 0
+}

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

@@ -0,0 +1,284 @@
+#!/usr/bin/env bash
+# scripts/forge-team/lib/verify.sh — 1:1 enforcement and orphan detection
+#
+# Functions:
+#   cmd_verify  — Check 5 health conditions and report results
+#
+# Checks:
+#   1. gh auth status (GitHub CLI authenticated)
+#   2. Identity mapped in team-map.jsonl
+#   3. Orphan Beads issues (Beads without GitHub counterpart)
+#   4. Orphan GitHub issues (GitHub without Beads counterpart)
+#   5. Assignee consistency between Beads and GitHub
+#
+# Env overrides (for testing):
+#   GH_CMD              — Path to gh binary (default: gh)
+#   BD_CMD              — Path to bd binary (default: bd)
+#   TEAM_MAP_ROOT       — Root dir for .beads/ and .github/ (default: .)
+#   VERIFY_MAPPING_FILE — Path to beads-mapping.json (default: $TEAM_MAP_ROOT/.github/beads-mapping.json)
+#
+# This file does NOT set errexit/pipefail — callers manage their own shell options.
+
+# Guard against double-sourcing
+if [[ -n "${_VERIFY_LIB_LOADED:-}" ]]; then
+  return 0 2>/dev/null || true
+fi
+_VERIFY_LIB_LOADED=1
+
+_VERIFY_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libraries (graceful fallback if missing)
+if [[ -f "$_VERIFY_DIR/agent-prompt.sh" ]]; then
+  source "$_VERIFY_DIR/agent-prompt.sh"
+fi
+if [[ -f "$_VERIFY_DIR/identity.sh" ]]; then
+  source "$_VERIFY_DIR/identity.sh"
+fi
+
+# ── Internal helpers ─────────────────────────────────────────────────────
+
+_verify_error() {
+  if declare -f agent_error &>/dev/null; then
+    agent_error "$1"
+  else
+    echo "ERROR: $1" >&2
+  fi
+}
+
+_verify_prompt() {
+  if declare -f agent_prompt &>/dev/null; then
+    agent_prompt "$1"
+  else
+    echo "PROMPT: $1" >&2
+  fi
+}
+
+_verify_info() {
+  if declare -f agent_info &>/dev/null; then
+    agent_info "$1"
+  else
+    echo "INFO: $1" >&2
+  fi
+}
+
+_mapping_file() {
+  local root="${TEAM_MAP_ROOT:-.}"
+  printf '%s' "${VERIFY_MAPPING_FILE:-$root/.github/beads-mapping.json}"
+}
+
+# ── _extract_beads_ids ───────────────────────────────────────────────────
+# Parse bd list output to extract beads IDs.
+# Input format: "◐ forge-aaa · Feature A" or "○ forge-bbb · Feature B"
+# Output: one ID per line
+_extract_beads_ids() {
+  local input="${1:-}"
+  if [[ -z "$input" ]]; then
+    return 0
+  fi
+  printf '%s\n' "$input" | grep -oP '(forge-[a-z0-9]+)' || true
+}
+
+# ── Public API ───────────────────────────────────────────────────────────
+
+# cmd_verify — Run all 5 health checks and report results.
+# Exit 0 if all clean, exit 1 if any issues found.
+cmd_verify() {
+  local gh_cmd="${GH_CMD:-gh}"
+  local bd_cmd="${BD_CMD:-bd}"
+  local issues_found=0
+
+  echo "forge team verify"
+  echo "═════════════════"
+  echo ""
+
+  # ── Check 1: gh auth status ──────────────────────────────────────────
+  local gh_auth_output
+  if gh_auth_output="$("$gh_cmd" auth status 2>&1)"; then
+    # Extract username from auth status output
+    local gh_user
+    gh_user="$(printf '%s' "$gh_auth_output" | grep -oP 'account\s+\K\S+' | head -1)"
+    if [[ -z "$gh_user" ]]; then
+      gh_user="$(printf '%s' "$gh_auth_output" | grep -oP 'Logged in to \S+ account \K\S+' | head -1)"
+    fi
+    echo "✓ GitHub CLI: authenticated${gh_user:+ as $gh_user}"
+  else
+    echo "✗ GitHub CLI: not authenticated"
+    _verify_error "GitHub CLI not authenticated. Run: gh auth login"
+    issues_found=$((issues_found + 1))
+    # Cannot proceed with other checks without auth
+    echo ""
+    echo "Result: $issues_found issue found — action needed"
+    return 1
+  fi
+
+  # ── Check 2: Identity mapped ────────────────────────────────────────
+  unset _GITHUB_USER_CACHE
+  local identity_user
+  if identity_user="$(get_github_user 2>/dev/null)"; then
+    local existing
+    existing="$(team_map_get "$identity_user" 2>/dev/null)"
+    if [[ "$existing" != "null" ]] && [[ -n "$existing" ]]; then
+      echo "✓ Identity: mapped in team-map.jsonl"
+    else
+      echo "✗ Identity: not found in team-map.jsonl"
+      _verify_prompt "Run: forge team add"
+      issues_found=$((issues_found + 1))
+    fi
+  else
+    echo "✗ Identity: could not detect"
+    _verify_prompt "Run: forge team add"
+    issues_found=$((issues_found + 1))
+  fi
+
+  # ── Check 3: Orphan Beads issues (Beads without GitHub) ─────────────
+  local bd_output
+  bd_output="$("$bd_cmd" list --status=open,in_progress 2>/dev/null)" || bd_output=""
+
+  local beads_ids
+  beads_ids="$(_extract_beads_ids "$bd_output")"
+
+  local beads_total=0
+  local beads_synced=0
+  local beads_orphans=()
+
+  if [[ -n "$beads_ids" ]]; then
+    while IFS= read -r bid; do
+      [[ -z "$bid" ]] && continue
+      beads_total=$((beads_total + 1))
+
+      # Check if this beads issue has github_issue state
+      local show_output
+      show_output="$("$bd_cmd" show "$bid" 2>/dev/null)" || show_output=""
+      if printf '%s' "$show_output" | grep -qP 'github_issue:\d+'; then
+        beads_synced=$((beads_synced + 1))
+      else
+        beads_orphans+=("$bid")
+      fi
+    done <<< "$beads_ids"
+  fi
+
+  if [[ ${#beads_orphans[@]} -eq 0 ]]; then
+    echo "✓ Beads→GitHub: ${beads_synced}/${beads_total} issues synced"
+  else
+    echo "✗ Beads→GitHub: ${#beads_orphans[@]} orphan issues found"
+    for orphan in "${beads_orphans[@]}"; do
+      _verify_prompt "${orphan} has no GitHub issue. Run: forge team sync-issue ${orphan}"
+    done
+    issues_found=$((issues_found + ${#beads_orphans[@]}))
+  fi
+
+  # ── Check 4: Orphan GitHub issues (GitHub without Beads) ────────────
+  local mapping_file
+  mapping_file="$(_mapping_file)"
+
+  local gh_issues_json
+  gh_issues_json="$("$gh_cmd" issue list --state open --json number,title --limit 100 2>/dev/null)" || gh_issues_json="[]"
+
+  local gh_issue_count
+  gh_issue_count="$(printf '%s' "$gh_issues_json" | jq 'length')"
+
+  local gh_orphans=()
+
+  if [[ "$gh_issue_count" -gt 0 ]] && [[ -f "$mapping_file" ]]; then
+    local mapping_content
+    mapping_content="$(cat "$mapping_file")"
+
+    local i=0
+    while [[ $i -lt $gh_issue_count ]]; do
+      local issue_num
+      issue_num="$(printf '%s' "$gh_issues_json" | jq -r ".[$i].number")"
+
+      # Check if this GitHub issue number is a key in the mapping
+      local mapped
+      mapped="$(printf '%s' "$mapping_content" | jq -r --arg n "$issue_num" '.[$n] // empty')"
+
+      if [[ -z "$mapped" ]]; then
+        gh_orphans+=("$issue_num")
+      fi
+      i=$((i + 1))
+    done
+  elif [[ "$gh_issue_count" -gt 0 ]] && [[ ! -f "$mapping_file" ]]; then
+    # No mapping file — all GitHub issues are orphans
+    local i=0
+    while [[ $i -lt $gh_issue_count ]]; do
+      local issue_num
+      issue_num="$(printf '%s' "$gh_issues_json" | jq -r ".[$i].number")"
+      gh_orphans+=("$issue_num")
+      i=$((i + 1))
+    done
+  fi
+
+  if [[ ${#gh_orphans[@]} -eq 0 ]]; then
+    local mapped_count=$((gh_issue_count))
+    echo "✓ GitHub→Beads: ${mapped_count}/${mapped_count} issues mapped"
+  else
+    echo "✗ GitHub→Beads: ${#gh_orphans[@]} orphan issues found"
+    for orphan_num in "${gh_orphans[@]}"; do
+      _verify_prompt "GitHub #${orphan_num} has no Beads issue. Run: forge team import #${orphan_num}"
+    done
+    issues_found=$((issues_found + ${#gh_orphans[@]}))
+  fi
+
+  # ── Check 5: Assignee consistency ───────────────────────────────────
+  local assignee_mismatches=()
+
+  if [[ -f "$mapping_file" ]] && [[ "$gh_issue_count" -gt 0 ]]; then
+    local mapping_content
+    mapping_content="$(cat "$mapping_file")"
+
+    local i=0
+    while [[ $i -lt $gh_issue_count ]]; do
+      local issue_num
+      issue_num="$(printf '%s' "$gh_issues_json" | jq -r ".[$i].number")"
+
+      # Check if issue is in mapping
+      local mapped_entry
+      mapped_entry="$(printf '%s' "$mapping_content" | jq -r --arg n "$issue_num" '.[$n] // empty')"
+
+      if [[ -n "$mapped_entry" ]]; then
+        local beads_assignee beads_id
+        beads_id="$(printf '%s' "$mapping_content" | jq -r --arg n "$issue_num" '.[$n].beads_id // empty')"
+        beads_assignee="$(printf '%s' "$mapping_content" | jq -r --arg n "$issue_num" '.[$n].assignee // empty')"
+
+        if [[ -n "$beads_assignee" ]]; then
+          # Get GitHub assignee
+          local gh_assignee_json
+          gh_assignee_json="$("$gh_cmd" issue view "$issue_num" --json assignees 2>/dev/null)" || gh_assignee_json="{}"
+          local gh_assignee
+          gh_assignee="$(printf '%s' "$gh_assignee_json" | jq -r '.assignees[0].login // empty')"
+
+          if [[ -n "$gh_assignee" ]] && [[ "$beads_assignee" != "$gh_assignee" ]]; then
+            assignee_mismatches+=("${beads_id:-issue-$issue_num}|$beads_assignee|$gh_assignee")
+          fi
+        fi
+      fi
+      i=$((i + 1))
+    done
+  fi
+
+  if [[ ${#assignee_mismatches[@]} -eq 0 ]]; then
+    echo "✓ Assignees: all consistent"
+  else
+    echo "✗ Assignees: ${#assignee_mismatches[@]} mismatches found"
+    for mismatch in "${assignee_mismatches[@]}"; do
+      local m_id m_beads m_github
+      m_id="$(printf '%s' "$mismatch" | cut -d'|' -f1)"
+      m_beads="$(printf '%s' "$mismatch" | cut -d'|' -f2)"
+      m_github="$(printf '%s' "$mismatch" | cut -d'|' -f3)"
+      _verify_info "${m_id} assignee mismatch: Beads=${m_beads}, GitHub=${m_github}"
+    done
+    issues_found=$((issues_found + ${#assignee_mismatches[@]}))
+  fi
+
+  # ── Summary ─────────────────────────────────────────────────────────
+  echo ""
+  if [[ $issues_found -eq 0 ]]; then
+    echo "Result: all checks passed"
+    return 0
+  else
+    local noun="issue"
+    [[ $issues_found -gt 1 ]] && noun="issues"
+    echo "Result: $issues_found $noun found — action needed"
+    return 1
+  fi
+}