@pennyfarthing/core 7.4.1 → 7.5.0

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 .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

@@ -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

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

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

@@ -1,44 +0,0 @@
-# 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.