@pennyfarthing/core 7.9.3 → 7.9.5

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

@@ -0,0 +1,212 @@
+#!/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
+}
+
+#############################################
+# Python Execution
+#############################################
+
+# get_python
+# Find the best Python interpreter (venv preferred, fallback to system)
+# Sets PYTHON_CMD variable
+#
+# Priority:
+#   1. PROJECT_ROOT/.venv/bin/python (project venv)
+#   2. python3 (system)
+#   3. python (legacy fallback)
+#
+# Usage:
+#   get_python
+#   $PYTHON_CMD -m pennyfarthing_scripts.jira view MSSCI-12345
+#
+get_python() {
+    # Find project root if not set
+    if [[ -z "${PROJECT_ROOT:-}" ]]; then
+        local d="$PWD"
+        while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
+            d="$(dirname "$d")"
+        done
+        PROJECT_ROOT="$d"
+    fi
+
+    # Check for project venv first
+    if [[ -x "${PROJECT_ROOT}/.venv/bin/python" ]]; then
+        PYTHON_CMD="${PROJECT_ROOT}/.venv/bin/python"
+    elif command -v python3 &> /dev/null; then
+        PYTHON_CMD="python3"
+    elif command -v python &> /dev/null; then
+        PYTHON_CMD="python"
+    else
+        error "Python not found. Install Python 3.11+ or create .venv"
+        return 1
+    fi
+}
+
+# run_python_module MODULE [ARGS...]
+# Run a pennyfarthing_scripts Python module with proper venv handling
+#
+# Usage:
+#   run_python_module jira view MSSCI-12345
+#   run_python_module sprint status
+#   run_python_module story size 3
+#
+run_python_module() {
+    get_python || return 1
+    local module="$1"
+    shift
+    exec $PYTHON_CMD -m "pennyfarthing_scripts.${module}" "$@"
+}

package/pennyfarthing-dist/scripts/lib/file-lock.sh

@@ -0,0 +1,269 @@
+#!/usr/bin/env zsh
+# File locking utilities for session file concurrency protection
+# Dev: Fanny Price - "We have all a better guide in ourselves."
+
+# Default timeout in seconds
+DEFAULT_LOCK_TIMEOUT=10
+
+# Stale lock threshold in seconds (5 minutes)
+STALE_LOCK_THRESHOLD=300
+
+# _get_lock_dir
+# Internal function to get lock directory (evaluated at call time)
+_get_lock_dir() {
+    echo "${PROJECT_ROOT:-.}/.session/.locks"
+}
+
+# _get_lock_file FILEPATH
+# Internal function to derive lock file path from target file
+#
+# Arguments:
+#   FILEPATH - Path to the file to lock
+#
+# Returns:
+#   Outputs the lock file path
+#
+_get_lock_file() {
+    local filepath="$1"
+    local filename
+    local lock_dir
+    filename=$(basename "$filepath")
+    lock_dir=$(_get_lock_dir)
+    echo "${lock_dir}/.${filename}.lock"
+}
+
+# _check_stale_lock LOCKFILE
+# Internal function to check and remove stale locks
+#
+# Arguments:
+#   LOCKFILE - Path to lock file to check
+#
+# Returns:
+#   0 if lock was stale and removed, 1 if lock is valid
+#
+_check_stale_lock() {
+    local lockfile="$1"
+
+    if [[ ! -f "$lockfile" ]]; then
+        return 1
+    fi
+
+    # Get lock file age in seconds
+    local now lock_mtime age
+    now=$(date +%s)
+
+    # macOS stat vs Linux stat differ
+    if [[ "$(uname)" == "Darwin" ]]; then
+        lock_mtime=$(stat -f %m "$lockfile" 2>/dev/null || echo 0)
+    else
+        lock_mtime=$(stat -c %Y "$lockfile" 2>/dev/null || echo 0)
+    fi
+
+    age=$((now - lock_mtime))
+
+    if ((age > STALE_LOCK_THRESHOLD)); then
+        # Log warning about stale lock
+        echo "[WARN] Removing stale lock: $lockfile (age: ${age}s)" >&2
+        rm -f "$lockfile"
+        return 0
+    fi
+
+    return 1
+}
+
+# lock_acquire FILEPATH [LOCK_TYPE] [TIMEOUT]
+# Acquire a lock on a file
+#
+# Arguments:
+#   FILEPATH  - Path to the file to lock
+#   LOCK_TYPE - "exclusive" (default) or "shared"
+#   TIMEOUT   - Timeout in seconds (default: 10)
+#
+# Returns:
+#   0 on success, 1 on timeout/failure
+#
+# Example:
+#   lock_acquire ".session/checkpoints.log"
+#   lock_acquire ".session/agent-logs.jsonl" "exclusive" 5
+#
+lock_acquire() {
+    local filepath="$1"
+    local lock_type="${2:-exclusive}"
+    local timeout="${3:-$DEFAULT_LOCK_TIMEOUT}"
+    local lockfile
+    local flock_opts
+    local start_time
+    local elapsed
+
+    lockfile=$(_get_lock_file "$filepath")
+    local lock_dir
+    lock_dir=$(_get_lock_dir)
+
+    # Ensure lock directory exists
+    mkdir -p "$lock_dir"
+
+    # Check for stale lock first (ignore return value)
+    _check_stale_lock "$lockfile" || true
+
+    # Set flock options based on lock type
+    case "$lock_type" in
+        shared)
+            flock_opts="-s"
+            ;;
+        exclusive|*)
+            flock_opts="-x"
+            ;;
+    esac
+
+    # Try to acquire lock with timeout
+    start_time=$(date +%s)
+    local my_pid="$$"
+
+    while true; do
+        # Try to create lock file atomically using ln (atomic on POSIX)
+        # Create a temp file with our PID, then try to hard-link it
+        local temp_lock="${lockfile}.${my_pid}"
+        echo "$my_pid" > "$temp_lock"
+
+        if ln "$temp_lock" "$lockfile" 2>/dev/null; then
+            rm -f "$temp_lock"
+            return 0
+        fi
+        rm -f "$temp_lock"
+
+        # Check if we've exceeded timeout
+        elapsed=$(( $(date +%s) - start_time ))
+        if ((elapsed >= timeout)); then
+            echo "[WARN] Lock timeout on $filepath after ${timeout}s" >&2
+            return 1
+        fi
+
+        # Check for stale lock
+        if _check_stale_lock "$lockfile" 2>/dev/null; then
+            continue  # Try again now that stale lock is removed
+        fi
+
+        # Wait a bit before retrying (100ms)
+        sleep 0.1
+    done
+}
+
+# lock_release FILEPATH
+# Release a lock on a file
+#
+# Arguments:
+#   FILEPATH - Path to the file to unlock
+#
+# Returns:
+#   0 on success
+#
+# Example:
+#   lock_release ".session/checkpoints.log"
+#
+lock_release() {
+    local filepath="$1"
+    local lockfile
+
+    lockfile=$(_get_lock_file "$filepath")
+
+    # Only remove if we own the lock (PID matches)
+    if [[ -f "$lockfile" ]]; then
+        local lock_pid
+        lock_pid=$(cat "$lockfile" 2>/dev/null || echo "")
+        if [[ "$lock_pid" == "$$" ]]; then
+            rm -f "$lockfile"
+        fi
+    fi
+
+    return 0
+}
+
+# with_lock FILEPATH LOCK_TYPE COMMAND...
+# Execute a command while holding a lock
+#
+# Arguments:
+#   FILEPATH  - Path to the file to lock
+#   LOCK_TYPE - "exclusive" or "shared"
+#   COMMAND   - Command and arguments to execute
+#
+# Returns:
+#   Exit code of the command, or 1 if lock failed
+#
+# Example:
+#   with_lock ".session/checkpoints.log" "exclusive" echo "data" >> file
+#   with_lock ".session/data.json" "shared" cat file
+#
+with_lock() {
+    local filepath="$1"
+    local lock_type="$2"
+    shift 2
+
+    if ! lock_acquire "$filepath" "$lock_type"; then
+        return 1
+    fi
+
+    # Execute command and capture exit code
+    local exit_code
+    "$@"
+    exit_code=$?
+
+    lock_release "$filepath"
+
+    return $exit_code
+}
+
+# lock_status FILEPATH
+# Check if a file is currently locked
+#
+# Arguments:
+#   FILEPATH - Path to the file to check
+#
+# Returns:
+#   0 if locked, 1 if not locked
+#   Outputs lock holder PID if locked
+#
+# Example:
+#   if lock_status ".session/checkpoints.log"; then
+#       echo "File is locked"
+#   fi
+#
+lock_status() {
+    local filepath="$1"
+    local lockfile
+
+    lockfile=$(_get_lock_file "$filepath")
+
+    if [[ -f "$lockfile" ]]; then
+        # Check for stale lock
+        if _check_stale_lock "$lockfile"; then
+            return 1
+        fi
+        cat "$lockfile"
+        return 0
+    fi
+
+    return 1
+}
+
+# lock_cleanup
+# Remove all stale locks in the lock directory
+#
+# Example:
+#   lock_cleanup
+#
+lock_cleanup() {
+    local lock_dir
+    lock_dir=$(_get_lock_dir)
+
+    if [[ ! -d "$lock_dir" ]]; then
+        return 0
+    fi
+
+    local lockfile
+    for lockfile in "$lock_dir"/.*.lock; do
+        [[ -f "$lockfile" ]] || continue
+        _check_stale_lock "$lockfile"
+    done
+}
+
+# Functions available when sourced

package/pennyfarthing-dist/scripts/lib/find-root.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env zsh
+# Shared utility: Find project root by .pennyfarthing/ marker
+#
+# DEPRECATED: Scripts invoked via run.sh already have PROJECT_ROOT set.
+# This file is kept for backwards compatibility with scripts that may be
+# run directly (not via run.sh).
+#
+# When run.sh executes a script, it sets PROJECT_ROOT before exec'ing,
+# so sourcing this file is a no-op (line 12 skips if already set).
+#
+# For new scripts: Just assume PROJECT_ROOT is set by the caller (run.sh).
+
+# Skip if PROJECT_ROOT is already set (e.g., by run.sh or CLAUDE_PROJECT_DIR)
+if [ -z "${PROJECT_ROOT:-}" ]; then
+    # Prefer SCRIPT_DIR (stable, set by caller) over PWD (may not be in project)
+    if [ -n "${SCRIPT_DIR:-}" ]; then
+        _find_root_dir="$SCRIPT_DIR"
+    else
+        _find_root_dir="$PWD"
+    fi
+
+    while [[ ! -d "$_find_root_dir/.pennyfarthing" ]] && [[ "$_find_root_dir" != "/" ]]; do
+        _find_root_dir="$(dirname "$_find_root_dir")"
+    done
+
+    if [[ -d "$_find_root_dir/.pennyfarthing" ]]; then
+        PROJECT_ROOT="$_find_root_dir"
+    else
+        echo "Error: Could not find project root (no .pennyfarthing/ directory found)" >&2
+        exit 1
+    fi
+    unset _find_root_dir
+fi
+
+export PROJECT_ROOT

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

@@ -0,0 +1,186 @@
+#!/usr/bin/env zsh
+# Structured JSON logging utilities for agent workflows
+# Dev: Fanny Price - "Let other pens dwell on guilt and misery."
+
+# 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
+
+# Log file location (evaluated dynamically)
+_get_log_file() {
+    echo "${PROJECT_ROOT:-.}/.session/agent-logs.jsonl"
+}
+
+# _log LEVEL MESSAGE [EXTRA_FIELDS]
+# Internal function to write structured log entry
+#
+# Arguments:
+#   LEVEL        - Log level (INFO, WARN, ERROR)
+#   MESSAGE      - Log message
+#   EXTRA_FIELDS - Optional extra JSON fields (must be valid JSON object contents)
+#
+_log() {
+    local level="$1"
+    local message="$2"
+    local extra="${3:-}"
+    local timestamp
+    local agent
+    local session
+    local log_file
+
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    agent="${AGENT_NAME:-unknown}"
+    session="${SESSION_ID:-}"
+    log_file=$(_get_log_file)
+
+    # Ensure directory exists
+    mkdir -p "$(dirname "$log_file")"
+
+    # Escape message for JSON (handle quotes and newlines)
+    message=$(printf '%s' "$message" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g' | tr '\n' ' ')
+
+    # Build JSON object
+    local json="{\"timestamp\":\"${timestamp}\",\"level\":\"${level}\",\"agent\":\"${agent}\",\"message\":\"${message}\""
+
+    # Add session_id if present
+    if [[ -n "$session" ]]; then
+        json="${json},\"session_id\":\"${session}\""
+    fi
+
+    # Add extra fields if provided
+    if [[ -n "$extra" ]]; then
+        json="${json},${extra}"
+    fi
+
+    json="${json}}"
+
+    # Acquire lock, write to log file, release lock
+    if lock_acquire "$log_file" "exclusive" 5 2>/dev/null; then
+        echo "$json" >> "$log_file"
+        lock_release "$log_file"
+    else
+        # Fallback: write without lock (better than failing)
+        echo "$json" >> "$log_file"
+    fi
+
+    # Also output to stderr for visibility (with color)
+    case "$level" in
+        INFO)  echo -e "\033[32m[INFO]\033[0m $message" >&2 ;;
+        WARN)  echo -e "\033[33m[WARN]\033[0m $message" >&2 ;;
+        ERROR) echo -e "\033[31m[ERROR]\033[0m $message" >&2 ;;
+    esac
+}
+
+# log_info MESSAGE [EXTRA_FIELDS]
+# Log an informational message
+#
+# Arguments:
+#   MESSAGE      - Log message
+#   EXTRA_FIELDS - Optional extra JSON fields
+#
+# Example:
+#   log_info "Starting workflow"
+#   log_info "File processed" '"file":"src/main.go","lines":42'
+#
+log_info() {
+    _log "INFO" "$1" "${2:-}"
+}
+
+# log_warn MESSAGE [EXTRA_FIELDS]
+# Log a warning message
+#
+# Arguments:
+#   MESSAGE      - Log message
+#   EXTRA_FIELDS - Optional extra JSON fields
+#
+# Example:
+#   log_warn "Context usage high"
+#   log_warn "Retry needed" '"attempt":2,"max":3'
+#
+log_warn() {
+    _log "WARN" "$1" "${2:-}"
+}
+
+# log_error MESSAGE [EXTRA_FIELDS]
+# Log an error message
+#
+# Arguments:
+#   MESSAGE      - Log message
+#   EXTRA_FIELDS - Optional extra JSON fields
+#
+# Example:
+#   log_error "Command failed"
+#   log_error "Test failure" '"test":"test_auth","exit_code":1'
+#
+log_error() {
+    _log "ERROR" "$1" "${2:-}"
+}
+
+# log_list [N]
+# List recent log entries
+#
+# Arguments:
+#   N - Number of entries to show (default: 20)
+#
+# Example:
+#   log_list
+#   log_list 50
+#
+log_list() {
+    local count=${1:-20}
+    local log_file
+    log_file=$(_get_log_file)
+
+    if [[ -f "$log_file" ]]; then
+        tail -n "$count" "$log_file"
+    fi
+}
+
+# log_clear
+# Remove all log entries
+#
+# Example:
+#   log_clear
+#
+log_clear() {
+    local log_file
+    log_file=$(_get_log_file)
+    rm -f "$log_file"
+}
+
+# log_rotate [MAX_LINES]
+# Rotate log file to prevent unbounded growth
+#
+# Arguments:
+#   MAX_LINES - Maximum lines to keep (default: 1000)
+#
+# Example:
+#   log_rotate
+#   log_rotate 500
+#
+log_rotate() {
+    local max_lines=${1:-1000}
+    local log_file
+    log_file=$(_get_log_file)
+
+    if [[ ! -f "$log_file" ]]; then
+        return 0
+    fi
+
+    # Acquire exclusive lock for rotation
+    if lock_acquire "$log_file" "exclusive" 5 2>/dev/null; then
+        local current_lines
+        current_lines=$(wc -l < "$log_file")
+
+        if ((current_lines > max_lines)); then
+            local temp_file
+            temp_file=$(mktemp)
+            tail -n "$max_lines" "$log_file" > "$temp_file"
+            mv "$temp_file" "$log_file"
+        fi
+        lock_release "$log_file"
+    fi
+}
+
+# Functions available when sourced