@pennyfarthing/core 6.6.0

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

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

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

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