@pennyfarthing/core 9.2.0 → 9.3.0

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,58 +0,0 @@
-#!/usr/bin/env bash
-# Shared utility: Find project root
-#
-# Resolution order:
-# 1. Honor explicit PROJECT_ROOT override (from Claude Code or user)
-# 2. BASH_SOURCE derivation (auto-detect caller's location)
-# 3. PWD walk looking for .pennyfarthing/ (fallback)
-#
-# Usage:
-#   source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
-#   # PROJECT_ROOT is now set
-
-# Allow explicit override
-if [[ -n "${PROJECT_ROOT:-}" ]]; then
-    export PROJECT_ROOT
-    return 0 2>/dev/null || exit 0
-fi
-
-# BASH_SOURCE approach: derive from caller's location
-# BASH_SOURCE[1] is the script that sourced us, BASH_SOURCE[0] is this file
-_caller_script="${BASH_SOURCE[1]:-}"
-if [[ -n "$_caller_script" ]]; then
-    _real_dir="$(cd "$(dirname "$_caller_script")" && pwd -P)"
-    if [[ "$_real_dir" == */pennyfarthing-dist/scripts/* ]] || \
-       [[ "$_real_dir" == */.pennyfarthing/scripts/* ]]; then
-        # Extract package root from path
-        _pkg="${_real_dir%/scripts/*}"
-        _pkg="${_pkg%/pennyfarthing-dist}"
-        _pkg="${_pkg%/.pennyfarthing}"
-        if [[ "$_pkg" == */node_modules/* ]]; then
-            PROJECT_ROOT="${_pkg%/node_modules/*}"
-        else
-            PROJECT_ROOT="$_pkg"
-        fi
-        unset _real_dir _pkg _caller_script
-        export PROJECT_ROOT
-        return 0 2>/dev/null || exit 0
-    fi
-    unset _real_dir
-fi
-unset _caller_script
-
-# Fallback: walk up from PWD looking for .pennyfarthing/
-_d="$PWD"
-while [[ ! -d "$_d/.pennyfarthing" ]] && [[ "$_d" != "/" ]]; do
-    _d="$(dirname "$_d")"
-done
-
-if [[ -d "$_d/.pennyfarthing" ]]; then
-    PROJECT_ROOT="$_d"
-else
-    echo "Error: Could not find .pennyfarthing/ directory" >&2
-    echo "Are you in a Pennyfarthing-enabled project?" >&2
-    exit 1
-fi
-
-unset _d
-export PROJECT_ROOT