@pennyfarthing/core 7.5.0 → 7.6.1

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 .claude/ 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/.claude" ]] && [[ "$_find_root_dir" != "/" ]]; do
+        _find_root_dir="$(dirname "$_find_root_dir")"
+    done
+
+    if [[ -d "$_find_root_dir/.claude" ]]; then
+        PROJECT_ROOT="$_find_root_dir"
+    else
+        echo "Error: Could not find project root (no .claude/ 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

package/pennyfarthing-dist/scripts/lib/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/misc/README.md

@@ -0,0 +1,44 @@
+# Miscellaneous Scripts
+
+Uncategorized utilities and one-off scripts.
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `deploy.sh` | Deployment script |
+| `doctor-dogfood.sh` | Health check for dogfooding setup |
+| `run-ci.sh` | Run CI locally |
+| `statusline.sh` | Status line configuration |
+| `uninstall.sh` | Uninstall Pennyfarthing from project |
+| `backlog.sh` | Backlog operations |
+| `repo-utils.sh` | Multi-repo utilities |
+| `repo-scan.sh` | Repository scanner |
+| `add-short-names.mjs` | Add short names to themes |
+| `migrate-bmad-workflow.mjs` | BMAD workflow migration |
+| `migrate-bmad-workflow.sh` | BMAD migration wrapper |
+| `find-related-work.sh` | Find related work items |
+| `check-status.sh` | Status checking utilities |
+| `session-cleanup.sh` | Clean up old sessions |
+| `generate-skill-docs.sh` | Generate skill documentation |
+| `log-skill-usage.sh` | Log skill invocations |
+| `skill-usage-report.sh` | Generate skill usage reports |
+| `run-timestamp.sh` | Timestamp utility |
+| `validate-subagent-frontmatter.sh` | Validate subagent YAML frontmatter |
+
+## Usage
+
+```bash
+.pennyfarthing/scripts/core/run.sh misc/doctor-dogfood.sh
+.pennyfarthing/scripts/core/run.sh misc/run-ci.sh
+```
+
+## Ownership
+
+- **Primary users:** Various
+- **Maintained by:** Core Pennyfarthing team
+
+## Note
+
+Scripts here may be candidates for moving to more specific categories
+as the codebase evolves.