@pennyfarthing/core 6.6.0

package/pennyfarthing-dist/scripts/utils/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

package/pennyfarthing-dist/scripts/utils/repo-scan.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env zsh
+# Pennyfarthing Repo Scanning Utilities
+# Provides functions for scanning git status and PRs across repos
+#
+# Usage: source scripts/utils/repo-scan.sh
+#
+# Functions:
+#   scan_repo_git_status REPO  - Get git status for a repo (repo|branch|uncommitted|ahead)
+#   scan_all_repos_status      - Get git status for all configured repos
+#   check_repo_pr REPO BRANCH  - Check for open PR on branch (returns URL or "none")
+
+# Don't exit on error - we want to handle errors gracefully
+set +e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+# Source repo-utils for multi-repo iteration
+source "$CLAUDE_PROJECT_DIR/scripts/repo-utils.sh" 2>/dev/null || true
+
+# ============================================================================
+# Git Status Functions
+# ============================================================================
+
+# Scan git status for a single repo
+# Returns: repo|branch|uncommitted_count|ahead_count
+scan_repo_git_status() {
+    local repo="$1"
+    local repo_path
+
+    # Handle both repo name (from config) and direct path
+    if [[ -d "$CLAUDE_PROJECT_DIR/$repo" ]]; then
+        repo_path="$CLAUDE_PROJECT_DIR/$repo"
+    elif declare -f get_repo_path &>/dev/null; then
+        repo_path=$(get_repo_full_path "$repo" 2>/dev/null)
+    else
+        repo_path="$CLAUDE_PROJECT_DIR/$repo"
+    fi
+
+    # If repo path doesn't exist, try PROJECT_ROOT itself (for pennyfarthing)
+    if [[ ! -d "$repo_path/.git" && -d "$CLAUDE_PROJECT_DIR/.git" && "$repo" == "pennyfarthing" ]]; then
+        repo_path="$CLAUDE_PROJECT_DIR"
+    fi
+
+    if [[ ! -d "$repo_path" ]]; then
+        echo "$repo|||"
+        return 1
+    fi
+
+    local branch uncommitted ahead
+
+    # Get current branch
+    branch=$(git -C "$repo_path" branch --show-current 2>/dev/null || echo "")
+
+    # Count uncommitted changes (staged + unstaged + untracked)
+    uncommitted=$(git -C "$repo_path" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+    # Count commits ahead of upstream
+    ahead=$(git -C "$repo_path" rev-list --count @{u}..HEAD 2>/dev/null || echo "0")
+
+    echo "$repo|$branch|$uncommitted|$ahead"
+}
+
+# Scan git status for all configured repos
+# Returns: one line per repo in scan_repo_git_status format
+scan_all_repos_status() {
+    # If repo-utils is available, use it
+    if declare -f get_repos &>/dev/null; then
+        for repo in $(get_repos); do
+            scan_repo_git_status "$repo"
+        done
+    else
+        # Fallback: scan common repo patterns
+        for dir in "$CLAUDE_PROJECT_DIR"/*; do
+            if [[ -d "$dir/.git" ]]; then
+                local repo_name
+                repo_name=$(basename "$dir")
+                scan_repo_git_status "$repo_name"
+            fi
+        done
+
+        # Also check PROJECT_ROOT itself
+        if [[ -d "$CLAUDE_PROJECT_DIR/.git" ]]; then
+            local root_name
+            root_name=$(basename "$CLAUDE_PROJECT_DIR")
+            scan_repo_git_status "$root_name"
+        fi
+    fi
+}
+
+# ============================================================================
+# PR Functions
+# ============================================================================
+
+# Check for open PR on a branch
+# Returns: PR URL or "none"
+check_repo_pr() {
+    local repo="$1"
+    local branch="$2"
+    local repo_path
+
+    # Handle both repo name (from config) and direct path
+    if [[ -d "$CLAUDE_PROJECT_DIR/$repo" ]]; then
+        repo_path="$CLAUDE_PROJECT_DIR/$repo"
+    elif declare -f get_repo_path &>/dev/null; then
+        repo_path=$(get_repo_full_path "$repo" 2>/dev/null)
+    else
+        repo_path="$CLAUDE_PROJECT_DIR/$repo"
+    fi
+
+    # If repo path doesn't exist, try PROJECT_ROOT itself
+    if [[ ! -d "$repo_path/.git" && -d "$CLAUDE_PROJECT_DIR/.git" && "$repo" == "pennyfarthing" ]]; then
+        repo_path="$CLAUDE_PROJECT_DIR"
+    fi
+
+    if [[ ! -d "$repo_path" ]]; then
+        echo "none"
+        return 0
+    fi
+
+    # Check if branch exists
+    if ! git -C "$repo_path" rev-parse --verify "$branch" &>/dev/null; then
+        echo "none"
+        return 0
+    fi
+
+    # Check for open PR using gh CLI
+    if command -v gh &>/dev/null; then
+        local pr_url
+        pr_url=$(cd "$repo_path" && gh pr view "$branch" --json url -q .url 2>/dev/null || echo "")
+        if [[ -n "$pr_url" ]]; then
+            echo "$pr_url"
+        else
+            echo "none"
+        fi
+    else
+        echo "none"
+    fi
+
+    return 0
+}

package/pennyfarthing-dist/scripts/utils/retry.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env zsh
+# Retry utilities with exponential backoff
+# Dev: Fanny Price - "We have all a better guide in ourselves, if we would attend to it."
+
+# retry_with_backoff MAX_ATTEMPTS INITIAL_DELAY MAX_DELAY COMMAND...
+# Retry a command with exponential backoff
+#
+# Arguments:
+#   MAX_ATTEMPTS   - Maximum number of attempts (default: 3)
+#   INITIAL_DELAY  - Initial delay in seconds (default: 1)
+#   MAX_DELAY      - Maximum delay cap in seconds (default: 30)
+#   COMMAND...     - Command to execute
+#
+# Returns:
+#   0 if command succeeds within attempts
+#   1 if all attempts exhausted
+#
+# Example:
+#   retry_with_backoff 3 1 10 curl -s https://api.example.com/health
+#
+retry_with_backoff() {
+    local max_attempts=${1:-3}
+    local delay=${2:-1}
+    local max_delay=${3:-30}
+    shift 3
+
+    local attempt=1
+    while true; do
+        # Try the command
+        if "$@"; then
+            return 0
+        fi
+
+        # Check if we've exhausted attempts
+        if ((attempt >= max_attempts)); then
+            return 1
+        fi
+
+        # Wait before retry
+        sleep "$delay"
+
+        # Exponential backoff with cap
+        delay=$((delay * 2))
+        if ((delay > max_delay)); then
+            delay=$max_delay
+        fi
+
+        attempt=$((attempt + 1))
+    done
+}
+
+# command_with_fallback PRIMARY_CMD FALLBACK_CMD
+# Execute primary command, fall back to alternative if it fails
+#
+# Arguments:
+#   PRIMARY_CMD   - Primary command to try (as string)
+#   FALLBACK_CMD  - Fallback command if primary fails (as string)
+#
+# Returns:
+#   Exit code of whichever command succeeds (or fallback's exit code)
+#
+# Example:
+#   command_with_fallback "git pull --ff-only" "git pull --no-rebase"
+#
+command_with_fallback() {
+    local primary_cmd="$1"
+    local fallback_cmd="$2"
+
+    if eval "$primary_cmd"; then
+        return 0
+    else
+        eval "$fallback_cmd"
+    fi
+}
+
+# Functions available when sourced - no export needed in zsh

package/pennyfarthing-dist/scripts/utils/run-timestamp.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+# Generate collision-resistant timestamp for benchmark runs
+# Format: YYYYMMDDTHHMMSS_NNNNNN (with microseconds)
+# Usage: RUN_TS=$(./scripts/utils/run-timestamp.sh)
+
+# macOS date supports %N for nanoseconds, truncate to microseconds
+date -u +%Y%m%dT%H%M%S_%N | cut -c1-22