@pennyfarthing/core 7.9.0 → 7.9.2

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

@@ -1,212 +0,0 @@
-#!/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

@@ -1,269 +0,0 @@
-#!/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

@@ -1,35 +0,0 @@
-#!/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

@@ -1,186 +0,0 @@
-#!/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