@pennyfarthing/core 7.5.0 → 7.6.1

package/pennyfarthing-dist/scripts/jira/sync-epic-jira.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+# Sync an epic and its stories to Jira
+# Usage: .pennyfarthing/scripts/core/run.sh sync-epic-jira.sh <epic-id> [--dry-run] [--transition] [--points] [--all]
+#
+# Example: .pennyfarthing/scripts/core/run.sh sync-epic-jira.sh MSSCI-11952
+# Example: .pennyfarthing/scripts/core/run.sh sync-epic-jira.sh MSSCI-11952 --all
+#
+# This script syncs status and story points from sprint YAML to Jira.
+# It wraps the existing jira-sync.mjs for better integration with /sprint skill.
+
+set -euo pipefail
+
+EPIC_ID="${1:-}"
+
+if [[ -z "$EPIC_ID" ]]; then
+  echo "Usage: sync-epic-jira.sh <epic-id> [options]"
+  echo ""
+  echo "Syncs an epic and its stories from sprint YAML to Jira."
+  echo ""
+  echo "Options:"
+  echo "  --dry-run      Show what would be done without making changes"
+  echo "  --transition   Transition Jira issues to match sprint YAML status"
+  echo "  --points       Sync story points from sprint YAML to Jira"
+  echo "  --all          Equivalent to --transition --points"
+  echo ""
+  echo "Examples:"
+  echo "  sync-epic-jira.sh MSSCI-11952              # Show sync status"
+  echo "  sync-epic-jira.sh MSSCI-11952 --dry-run    # Preview changes"
+  echo "  sync-epic-jira.sh MSSCI-11952 --all        # Sync status and points"
+  exit 1
+fi
+
+# PROJECT_ROOT should be set by run.sh, but find it if not
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
+
+if [[ ! -f "$SPRINT_FILE" ]]; then
+  echo "Error: Sprint file not found at $SPRINT_FILE"
+  exit 1
+fi
+
+if ! command -v yq &> /dev/null; then
+  echo "Error: yq is required but not installed"
+  echo "Install with: brew install yq"
+  exit 1
+fi
+
+# Check if epic exists in sprint YAML
+EPIC_EXISTS=$(yq ".epics[] | select(.id == \"$EPIC_ID\") | .id" "$SPRINT_FILE" 2>/dev/null || echo "")
+
+if [[ -z "$EPIC_EXISTS" ]]; then
+  echo "Error: Epic $EPIC_ID not found in $SPRINT_FILE"
+  echo ""
+  echo "Available epics:"
+  yq '.epics[].id' "$SPRINT_FILE" 2>/dev/null || echo "  None found"
+  exit 1
+fi
+
+# Extract epic number for jira-sync.mjs compatibility
+# jira-sync.mjs expects epic number (e.g., 35) not full ID
+# But it also accepts Jira keys directly
+# Let's check if this is a Jira key (MSSCI-XXXXX) or local ID
+
+# Pass through to jira-sync.mjs with remaining arguments
+JIRA_SYNC_SCRIPT="$PROJECT_ROOT/.pennyfarthing/scripts/utils/jira/jira-sync.mjs"
+
+if [[ ! -f "$JIRA_SYNC_SCRIPT" ]]; then
+  # Try alternate location
+  JIRA_SYNC_SCRIPT="$PROJECT_ROOT/pennyfarthing-dist/scripts/utils/jira/jira-sync.mjs"
+fi
+
+if [[ ! -f "$JIRA_SYNC_SCRIPT" ]]; then
+  echo "Error: jira-sync.mjs not found"
+  exit 1
+fi
+
+# Build arguments for jira-sync.mjs
+shift  # Remove epic-id from arguments
+SYNC_ARGS=("$EPIC_ID")
+
+# Handle --all flag
+for arg in "$@"; do
+  case "$arg" in
+    --all)
+      SYNC_ARGS+=("--transition" "--points")
+      ;;
+    *)
+      SYNC_ARGS+=("$arg")
+      ;;
+  esac
+done
+
+echo "Syncing epic $EPIC_ID to Jira..."
+echo ""
+
+# Run jira-sync.mjs
+exec node "$JIRA_SYNC_SCRIPT" "${SYNC_ARGS[@]}"

package/pennyfarthing-dist/scripts/jira/sync-epic-to-jira.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env zsh
+# Sync Pennyfarthing Epic to Jira MSSCI Project using jira
+# Usage: ./scripts/sync-epic-to-jira.sh <epic_number> [--dry-run] [--with-comments]
+#
+# Prerequisites:
+#   - jira installed: brew install ankitpokhrel/jira/jira
+#   - jira configured: jira init
+#   - JIRA_API_TOKEN environment variable set
+#
+# Options:
+#   --dry-run         Show what would be done without making changes
+#   --with-comments   (Deprecated - kept for compatibility)
+
+# Delegate to jira-sync.sh which implements the actual sync logic
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec "${SCRIPT_DIR}/jira-sync.sh" "$@"

package/pennyfarthing-dist/scripts/lib/README.md

@@ -0,0 +1,29 @@
+# Library Scripts
+
+Shared bash libraries sourced by other scripts.
+
+## Libraries
+
+| Script | Purpose |
+|--------|---------|
+| `common.sh` | Common utilities (colors, logging basics) |
+| `logging.sh` | Structured logging functions |
+| `retry.sh` | Retry logic with exponential backoff |
+| `checkpoint.sh` | Checkpointing for long-running operations |
+| `file-lock.sh` | File locking utilities |
+| `background-tasks.sh` | Background task management |
+| `find-root.sh` | Project root finder |
+
+## Usage
+
+These are sourced by other scripts, not run directly:
+
+```bash
+source "$SCRIPTS_DIR/lib/common.sh"
+source "$SCRIPTS_DIR/lib/logging.sh"
+```
+
+## Ownership
+
+- **Primary users:** All scripts
+- **Maintained by:** Core Pennyfarthing team

package/pennyfarthing-dist/scripts/lib/background-tasks.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# Background task tracking utilities for session files
+#
+# Usage:
+#   source $CLAUDE_PROJECT_DIR/scripts/lib/background-tasks.sh
+#
+# Functions:
+#   bg_task_add <session_file> <task_id> <subagent_type> <description>
+#   bg_task_update <session_file> <task_id> <status>
+#   bg_task_cleanup <session_file>
+#   bg_task_list <session_file>
+#   bg_task_check <session_file>
+#
+# Example:
+#   # After spawning background task
+#   bg_task_add "$SESSION_FILE" "abc123" "testing-runner" "Background test run"
+#
+#   # After TaskOutput returns
+#   bg_task_update "$SESSION_FILE" "abc123" "completed"
+#   bg_task_cleanup "$SESSION_FILE"
+
+set -euo pipefail
+
+# Helper: count pattern matches in file (returns 0 if no matches)
+# grep -c outputs "0" AND exits 1 when no matches, so we capture and fallback separately
+_count_matches() {
+    local count
+    count=$(grep -c "$1" "$2" 2>/dev/null) || count=0
+    echo "$count"
+}
+
+# Add a background task to session file
+# Creates the Background Tasks section if it doesn't exist
+bg_task_add() {
+    local session_file="$1"
+    local task_id="$2"
+    local subagent_type="$3"
+    local description="${4:-}"
+    local timestamp
+    timestamp=$(date +"%H:%M")
+
+    if [[ ! -f "$session_file" ]]; then
+        echo "ERROR: Session file not found: $session_file" >&2
+        return 1
+    fi
+
+    # Check if Background Tasks section exists
+    if ! grep -q "^## Background Tasks" "$session_file" 2>/dev/null; then
+        # Add section before Workflow Tracking if present, otherwise at end
+        if grep -q "^## Workflow Tracking" "$session_file"; then
+            # Insert before Workflow Tracking using awk
+            awk '/^## Workflow Tracking/ {
+                print "## Background Tasks\n"
+                print "| Task ID | Type | Started | Status | Description |"
+                print "|---------|------|---------|--------|-------------|"
+                print ""
+            } {print}' "$session_file" > "${session_file}.tmp" && mv "${session_file}.tmp" "$session_file"
+        else
+            # Append to end
+            cat >> "$session_file" << EOF
+
+## Background Tasks
+
+| Task ID | Type | Started | Status | Description |
+|---------|------|---------|--------|-------------|
+EOF
+        fi
+    fi
+
+    # Add task row after the table header
+    awk -v tid="$task_id" -v stype="$subagent_type" -v ts="$timestamp" -v desc="$description" '
+        /^\|[-]+\|/ && in_section {
+            print
+            print "| " tid " | " stype " | " ts " | running | " desc " |"
+            next
+        }
+        /^## Background Tasks/ { in_section=1 }
+        /^## / && !/^## Background Tasks/ { in_section=0 }
+        { print }
+    ' "$session_file" > "${session_file}.tmp" && mv "${session_file}.tmp" "$session_file"
+
+    echo "Added background task: $task_id ($subagent_type)"
+}
+
+# Update background task status
+# Status: running, completed, error
+bg_task_update() {
+    local session_file="$1"
+    local task_id="$2"
+    local new_status="$3"
+
+    if [[ ! -f "$session_file" ]]; then
+        echo "ERROR: Session file not found: $session_file" >&2
+        return 1
+    fi
+
+    if ! grep -q "| $task_id |" "$session_file" 2>/dev/null; then
+        echo "WARNING: Task $task_id not found in session file" >&2
+        return 0
+    fi
+
+    # Update the status column for this task
+    sed -i '' "s/| $task_id |\\([^|]*\\)|\\([^|]*\\)| running |/| $task_id |\\1|\\2| $new_status |/" "$session_file"
+    echo "Updated task $task_id: $new_status"
+}
+
+# Remove completed and error tasks from session file
+bg_task_cleanup() {
+    local session_file="$1"
+
+    if [[ ! -f "$session_file" ]]; then
+        echo "ERROR: Session file not found: $session_file" >&2
+        return 1
+    fi
+
+    # Count tasks to remove
+    local completed_count
+    completed_count=$(_count_matches "| completed |" "$session_file")
+    local error_count
+    error_count=$(_count_matches "| error |" "$session_file")
+
+    if [[ "$completed_count" -gt 0 ]] || [[ "$error_count" -gt 0 ]]; then
+        sed -i '' '/| completed |/d' "$session_file"
+        sed -i '' '/| error |/d' "$session_file"
+        echo "Cleaned up $completed_count completed, $error_count errored tasks"
+    fi
+}
+
+# List active (running) background tasks
+bg_task_list() {
+    local session_file="$1"
+
+    if [[ ! -f "$session_file" ]]; then
+        echo "No session file"
+        return 0
+    fi
+
+    local running_tasks
+    running_tasks=$(grep "| running |" "$session_file" 2>/dev/null || true)
+
+    if [[ -n "$running_tasks" ]]; then
+        echo "$running_tasks"
+    else
+        echo "No active background tasks"
+    fi
+}
+
+# Check for active background tasks (returns 0 if tasks exist, 1 if none)
+# Useful for conditional logic in scripts
+bg_task_check() {
+    local session_file="$1"
+
+    if [[ ! -f "$session_file" ]]; then
+        return 1
+    fi
+
+    grep -q "| running |" "$session_file" 2>/dev/null
+}
+
+# Print summary of all background tasks
+bg_task_summary() {
+    local session_file="$1"
+
+    if [[ ! -f "$session_file" ]]; then
+        echo "No session file"
+        return 0
+    fi
+
+    local running
+    running=$(_count_matches "| running |" "$session_file")
+    local completed
+    completed=$(_count_matches "| completed |" "$session_file")
+    local errored
+    errored=$(_count_matches "| error |" "$session_file")
+
+    echo "Background tasks: $running running, $completed completed, $errored errored"
+}

package/pennyfarthing-dist/scripts/lib/checkpoint.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env zsh
+# Session checkpointing utilities
+# Dev: Fanny Price - "I was quiet, but I was not blind."
+
+# Source file locking utilities
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=file-lock.sh
+source "${SCRIPT_DIR}/file-lock.sh" 2>/dev/null || true
+
+# Checkpoint file location (evaluated dynamically)
+_get_checkpoint_file() {
+    echo "${PROJECT_ROOT:-.}/.session/checkpoints.log"
+}
+
+# checkpoint_save LABEL DATA
+# Save a checkpoint with timestamp
+#
+# Arguments:
+#   LABEL - Identifier for this checkpoint
+#   DATA  - Data to save (string)
+#
+# Format: ISO_TIMESTAMP|LABEL|DATA
+#
+# Example:
+#   checkpoint_save "story_phase" "dev"
+#   checkpoint_save "last_file" "src/main.go:42"
+#
+checkpoint_save() {
+    local label="$1"
+    local data="$2"
+    local timestamp
+    local checkpoint_file
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    checkpoint_file=$(_get_checkpoint_file)
+
+    # Ensure directory exists
+    mkdir -p "$(dirname "$checkpoint_file")"
+
+    # Acquire exclusive lock, append checkpoint, release lock
+    if lock_acquire "$checkpoint_file" "exclusive" 5 2>/dev/null; then
+        echo "${timestamp}|${label}|${data}" >> "$checkpoint_file"
+        lock_release "$checkpoint_file"
+    else
+        # Fallback: append without lock (better than failing)
+        echo "${timestamp}|${label}|${data}" >> "$checkpoint_file"
+    fi
+}
+
+# checkpoint_restore LABEL
+# Restore the most recent checkpoint with given label
+#
+# Arguments:
+#   LABEL - Identifier to look up
+#
+# Returns:
+#   Outputs the data portion of the most recent matching checkpoint
+#   Empty if no match found
+#
+# Example:
+#   phase=$(checkpoint_restore "story_phase")
+#
+checkpoint_restore() {
+    local label="$1"
+    local checkpoint_file
+    checkpoint_file=$(_get_checkpoint_file)
+
+    if [[ ! -f "$checkpoint_file" ]]; then
+        return 0
+    fi
+
+    # Find entries with matching label, take the last one, extract data field
+    # Use || true to handle case where grep finds no matches
+    grep "|${label}|" "$checkpoint_file" 2>/dev/null | tail -1 | cut -d'|' -f3- || true
+}
+
+# checkpoint_list
+# List recent checkpoints (last 20)
+#
+# Example:
+#   checkpoint_list
+#
+checkpoint_list() {
+    local checkpoint_file
+    checkpoint_file=$(_get_checkpoint_file)
+
+    if [[ -f "$checkpoint_file" ]]; then
+        tail -20 "$checkpoint_file"
+    fi
+}
+
+# checkpoint_clear
+# Remove all checkpoints
+#
+# Example:
+#   checkpoint_clear
+#
+checkpoint_clear() {
+    local checkpoint_file
+    checkpoint_file=$(_get_checkpoint_file)
+    rm -f "$checkpoint_file"
+}
+
+# checkpoint_rotate MAX_LINES
+# Rotate checkpoint file to prevent unbounded growth
+#
+# Arguments:
+#   MAX_LINES - Maximum lines to keep (default: 1000)
+#
+# Example:
+#   checkpoint_rotate 500
+#
+checkpoint_rotate() {
+    local max_lines=${1:-1000}
+    local checkpoint_file
+    checkpoint_file=$(_get_checkpoint_file)
+
+    if [[ ! -f "$checkpoint_file" ]]; then
+        return 0
+    fi
+
+    # Acquire exclusive lock for rotation
+    if lock_acquire "$checkpoint_file" "exclusive" 5 2>/dev/null; then
+        local current_lines
+        current_lines=$(wc -l < "$checkpoint_file")
+
+        if ((current_lines > max_lines)); then
+            local temp_file
+            temp_file=$(mktemp)
+            tail -n "$max_lines" "$checkpoint_file" > "$temp_file"
+            mv "$temp_file" "$checkpoint_file"
+        fi
+        lock_release "$checkpoint_file"
+    fi
+}
+
+# Functions available when sourced

package/pennyfarthing-dist/scripts/lib/common.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env zsh
+# Common utility functions for Pennyfarthing scripts
+# Source this file: source "${SCRIPT_DIR}/lib/common.sh"
+#
+# Provides:
+#   - Output helpers: success, info, warn, error
+#   - Dry-run check: dry_run_check
+#   - JQL escaping: escape_for_jql
+#   - Jira JSON helpers: get_issue_json, get_jira_field
+
+#############################################
+# Output Helpers
+#############################################
+
+# Color codes
+_RED='\033[31m'
+_GREEN='\033[32m'
+_YELLOW='\033[33m'
+_BLUE='\033[34m'
+_NC='\033[0m'  # No Color
+
+# success MESSAGE
+# Print a success message in green (to stderr for visibility)
+success() {
+    echo -e "${_GREEN}[OK]${_NC} $1" >&2
+}
+
+# info MESSAGE
+# Print an info message in blue (to stderr for visibility)
+info() {
+    echo -e "${_BLUE}[INFO]${_NC} $1" >&2
+}
+
+# warn MESSAGE
+# Print a warning message in yellow (to stderr for visibility)
+warn() {
+    echo -e "${_YELLOW}[WARN]${_NC} $1" >&2
+}
+
+# error MESSAGE
+# Print an error message in red (to stderr, does NOT exit)
+error() {
+    echo -e "${_RED}[ERROR]${_NC} $1" >&2
+}
+
+#############################################
+# Dry-Run Support
+#############################################
+
+# dry_run_check ACTION
+# Check if DRY_RUN is enabled and print a warning
+# Returns 0 if dry-run is active (caller should skip the action)
+# Returns 1 if dry-run is NOT active (caller should proceed)
+#
+# Usage:
+#   if dry_run_check "create epic: $summary"; then
+#       echo "DRYRUN-EPIC-001"
+#       return
+#   fi
+#   # ... actual implementation
+#
+dry_run_check() {
+    local action="$1"
+    if [ "$DRY_RUN" = true ]; then
+        warn "[DRY-RUN] Would ${action}"
+        return 0
+    fi
+    return 1
+}
+
+#############################################
+# JQL Helpers
+#############################################
+
+# escape_for_jql STRING
+# Escape a string for use in JQL queries
+# Escapes double quotes and other special characters
+#
+# Usage:
+#   local escaped=$(escape_for_jql "$summary")
+#   jira issue list --jql "summary~'${escaped}'"
+#
+escape_for_jql() {
+    echo "$1" | sed 's/"/\\"/g'
+}
+
+#############################################
+# Jira JSON Helpers
+#############################################
+
+# get_issue_json ISSUE_KEY
+# Fetch Jira issue as JSON with error handling
+# Returns empty object {} if issue not found
+# Sets exit code 1 if fetch failed
+#
+# Usage:
+#   local json=$(get_issue_json "PROJ-123")
+#   if [ -z "$json" ] || [ "$json" = "{}" ]; then
+#       warn "Could not fetch issue"
+#   fi
+#
+get_issue_json() {
+    local key="$1"
+    local json
+    json=$(jira issue view "$key" --raw 2>/dev/null)
+    if [ -z "$json" ]; then
+        echo "{}"
+        return 1
+    fi
+    echo "$json"
+}
+
+# get_jira_field JSON FIELD_PATH [DEFAULT]
+# Extract a field from Jira issue JSON using jq
+#
+# Arguments:
+#   JSON        - The JSON string to parse
+#   FIELD_PATH  - jq path expression (e.g., '.fields.summary')
+#   DEFAULT     - Optional default value if field is null/empty
+#
+# Usage:
+#   local summary=$(get_jira_field "$json" '.fields.summary')
+#   local points=$(get_jira_field "$json" '.fields.customfield_10031' '0')
+#
+get_jira_field() {
+    local json="$1"
+    local field_path="$2"
+    local default="${3:-}"
+
+    if [ -n "$default" ]; then
+        echo "$json" | jq -r "${field_path} // \"${default}\""
+    else
+        echo "$json" | jq -r "${field_path} // empty"
+    fi
+}
+
+#############################################
+# Dependency Checks
+#############################################
+
+# check_dependencies
+# Check for common required tools
+# Can be extended with optional checks
+check_dependencies() {
+    local missing=()
+
+    # Check for jq (required for JSON parsing)
+    if ! command -v jq &> /dev/null; then
+        missing+=("jq")
+        error "jq not found - install with: brew install jq"
+    fi
+
+    if [ ${#missing[@]} -gt 0 ]; then
+        return 1
+    fi
+    return 0
+}