@pennyfarthing/core 7.0.2 → 7.4.0

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

@@ -1,157 +0,0 @@
-#!/usr/bin/env zsh
-# Common utility functions for Pennyfarthing scripts
-# Source this file: source "${SCRIPT_DIR}/utils/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
-}

package/pennyfarthing-dist/scripts/utils/create-feature-branches.sh

@@ -1,230 +0,0 @@
-#!/usr/bin/env zsh
-# Create or checkout feature branches in conductor repos
-# Idempotent, worktree-aware, branches from develop
-
-set -e
-
-# Load environment
-if [ -f .env ]; then
-    set -a; source .env; set +a
-elif [ -f ../.env ]; then
-    set -a; source ../.env; set +a
-fi
-
-# Find project root
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-source "$SCRIPT_DIR/find-root.sh"
-
-show_help() {
-    cat << EOF
-Create Feature Branches - Idempotent branch creation/checkout
-
-Usage: ./create-feature-branches.sh <branch-name> [repos]
-
-Arguments:
-  branch-name    Branch name (e.g., feat/11-2-file-preview)
-  repos          Which repos to branch (default: all)
-                 Options: api, ui, all
-
-Repo Options:
-  api     - conductor-api only
-  ui      - conductor-ui only
-  all     - both repos (default)
-
-Examples:
-  # All repos (default)
-  ./create-feature-branches.sh feat/cross-repo-feature
-
-  # Conductor UI only
-  ./create-feature-branches.sh feat/11-2-ui-component ui
-
-  # Conductor API only
-  ./create-feature-branches.sh fix/validation-bug api
-
-Behavior:
-  - Idempotent: Checks out existing branches or creates new ones
-  - Worktree-aware: Detects main checkout vs worktree
-  - Always branches from develop
-  - Fetches latest develop before branching
-
-EOF
-}
-
-if [ -z "$1" ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
-    show_help
-    exit 0
-fi
-
-BRANCH_NAME="$1"
-REPOS="${2:-all}"
-
-# Validate repos parameter
-if [[ ! "$REPOS" =~ ^(api|ui|all)$ ]]; then
-    echo "❌ Error: repos must be one of: api, ui, all"
-    echo "   Got: $REPOS"
-    echo ""
-    echo "Options:"
-    echo "  api     - conductor-api only"
-    echo "  ui      - conductor-ui only"
-    echo "  all     - both repos (default)"
-    exit 1
-fi
-
-# Detect if we're in a worktree
-CURRENT_DIR=$(pwd)
-if [[ "$CURRENT_DIR" == *"/worktrees/"* ]]; then
-    # Extract worktree name from path
-    WORKTREE_NAME=$(echo "$CURRENT_DIR" | sed -E 's|.*/worktrees/([^/]+).*|\1|')
-    REPO_BASE="$PROJECT_ROOT/worktrees/$WORKTREE_NAME"
-    echo "📂 Detected worktree: $WORKTREE_NAME"
-else
-    REPO_BASE="$PROJECT_ROOT"
-    echo "📂 Using main checkout"
-fi
-
-# Array to track processed repos for verification
-declare -a PROCESSED_REPOS
-
-# Function to create or checkout branch in a repo
-create_or_checkout_branch() {
-    local repo_path=$1
-    local repo_name=$2
-
-    if [ ! -d "$repo_path" ]; then
-        echo "⚠️  Skipping $repo_name: directory not found at $repo_path"
-        return
-    fi
-
-    cd "$repo_path"
-
-    echo ""
-    echo "🔧 Processing $repo_name..."
-
-    # Fetch latest from remote
-    echo "   Fetching from origin..."
-    git fetch origin --quiet
-
-    # Check if branch exists locally
-    if git show-ref --verify --quiet "refs/heads/$BRANCH_NAME"; then
-        echo "   ✅ Branch exists locally, checking out: $BRANCH_NAME"
-        git checkout "$BRANCH_NAME"
-    # Check if branch exists on remote
-    elif git show-ref --verify --quiet "refs/remotes/origin/$BRANCH_NAME"; then
-        echo "   ✅ Branch exists on remote, checking out and tracking: $BRANCH_NAME"
-        git checkout -b "$BRANCH_NAME" "origin/$BRANCH_NAME"
-    else
-        # Branch doesn't exist, create from develop
-        echo "   🌿 Creating new branch from develop: $BRANCH_NAME"
-
-        # Make sure we have latest develop
-        git fetch origin develop:develop --quiet 2>/dev/null || true
-
-        # Checkout develop first
-        if git show-ref --verify --quiet "refs/heads/develop"; then
-            git checkout develop --quiet
-            git pull origin develop --quiet
-        else
-            echo "   ⚠️  Local develop doesn't exist, fetching from remote"
-            git fetch origin develop:develop --quiet
-            git checkout develop --quiet
-        fi
-
-        # Create new branch
-        git checkout -b "$BRANCH_NAME"
-        echo "   ✅ Created: $BRANCH_NAME"
-    fi
-
-    # Show current status
-    CURRENT_BRANCH=$(git branch --show-current)
-    echo "   📍 Now on: $CURRENT_BRANCH"
-
-    # Track this repo for verification
-    PROCESSED_REPOS+=("$repo_path:$repo_name")
-}
-
-echo "🌿 Creating/checking out feature branches..."
-echo "   Branch: $BRANCH_NAME"
-echo "   Repos: $REPOS"
-
-# Process repos based on selection
-case "$REPOS" in
-    api)
-        create_or_checkout_branch "$REPO_BASE/conductor-api" "conductor-api"
-        ;;
-    ui)
-        create_or_checkout_branch "$REPO_BASE/conductor-ui" "conductor-ui"
-        ;;
-    all)
-        create_or_checkout_branch "$REPO_BASE/conductor-api" "conductor-api"
-        create_or_checkout_branch "$REPO_BASE/conductor-ui" "conductor-ui"
-        ;;
-esac
-
-echo ""
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo "🔍 Verification Summary"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-
-# Verify each processed repo
-for repo_info in "${PROCESSED_REPOS[@]}"; do
-    repo_path="${repo_info%%:*}"
-    repo_name="${repo_info##*:}"
-
-    if [ -d "$repo_path" ]; then
-        cd "$repo_path"
-
-        echo ""
-        echo "📦 $repo_name"
-        echo "   Path: $repo_path"
-
-        # Current branch
-        CURRENT_BRANCH=$(git branch --show-current)
-        echo "   Branch: $CURRENT_BRANCH"
-
-        # Check if branch matches expected
-        if [ "$CURRENT_BRANCH" = "$BRANCH_NAME" ]; then
-            echo "   ✅ Branch matches: $BRANCH_NAME"
-        else
-            echo "   ⚠️  Branch mismatch! Expected: $BRANCH_NAME, Got: $CURRENT_BRANCH"
-        fi
-
-        # Latest commit
-        COMMIT_INFO=$(git log -1 --format="%h - %s" 2>/dev/null)
-        echo "   Commit: $COMMIT_INFO"
-
-        # Check remote tracking
-        UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "none")
-        if [ "$UPSTREAM" != "none" ]; then
-            echo "   Remote: $UPSTREAM"
-
-            # Check if up to date with remote
-            git fetch origin "$CURRENT_BRANCH" --quiet 2>/dev/null || true
-            LOCAL=$(git rev-parse @ 2>/dev/null)
-            REMOTE=$(git rev-parse @{u} 2>/dev/null || echo "none")
-
-            if [ "$LOCAL" = "$REMOTE" ]; then
-                echo "   Status: ✅ Up to date with remote"
-            elif [ "$REMOTE" = "none" ]; then
-                echo "   Status: ⚠️  No remote branch yet (push needed)"
-            else
-                BEHIND=$(git rev-list --count HEAD..@{u} 2>/dev/null || echo "0")
-                AHEAD=$(git rev-list --count @{u}..HEAD 2>/dev/null || echo "0")
-                if [ "$AHEAD" -gt 0 ] && [ "$BEHIND" -gt 0 ]; then
-                    echo "   Status: ⚠️  Diverged ($AHEAD ahead, $BEHIND behind)"
-                elif [ "$AHEAD" -gt 0 ]; then
-                    echo "   Status: ⬆️  $AHEAD commit(s) ahead of remote"
-                elif [ "$BEHIND" -gt 0 ]; then
-                    echo "   Status: ⬇️  $BEHIND commit(s) behind remote"
-                fi
-            fi
-        else
-            echo "   Remote: none (local branch only)"
-            echo "   Status: ⚠️  Not tracking remote (push with -u needed)"
-        fi
-    fi
-done
-
-echo ""
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo "✅ Done! All branches verified and ready."
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

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