@pennyfarthing/core 6.6.0

package/pennyfarthing-dist/scripts/utils/background-tasks.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# Background task tracking utilities for session files
+#
+# Usage:
+#   source $CLAUDE_PROJECT_DIR/scripts/utils/background-tasks.sh
+#
+# Functions:
+#   bg_task_add <session_file> <task_id> <subagent_type> <description>
+#   bg_task_update <session_file> <task_id> <status>
+#   bg_task_cleanup <session_file>
+#   bg_task_list <session_file>
+#   bg_task_check <session_file>
+#
+# Example:
+#   # After spawning background task
+#   bg_task_add "$SESSION_FILE" "abc123" "testing-runner" "Background test run"
+#
+#   # After TaskOutput returns
+#   bg_task_update "$SESSION_FILE" "abc123" "completed"
+#   bg_task_cleanup "$SESSION_FILE"
+
+set -euo pipefail
+
+# Helper: count pattern matches in file (returns 0 if no matches)
+# grep -c outputs "0" AND exits 1 when no matches, so we capture and fallback separately
+_count_matches() {
+    local count
+    count=$(grep -c "$1" "$2" 2>/dev/null) || count=0
+    echo "$count"
+}
+
+# Add a background task to session file
+# Creates the Background Tasks section if it doesn't exist
+bg_task_add() {
+    local session_file="$1"
+    local task_id="$2"
+    local subagent_type="$3"
+    local description="${4:-}"
+    local timestamp
+    timestamp=$(date +"%H:%M")
+
+    if [[ ! -f "$session_file" ]]; then
+        echo "ERROR: Session file not found: $session_file" >&2
+        return 1
+    fi
+
+    # Check if Background Tasks section exists
+    if ! grep -q "^## Background Tasks" "$session_file" 2>/dev/null; then
+        # Add section before Workflow Tracking if present, otherwise at end
+        if grep -q "^## Workflow Tracking" "$session_file"; then
+            # Insert before Workflow Tracking using awk
+            awk '/^## Workflow Tracking/ {
+                print "## Background Tasks\n"
+                print "| Task ID | Type | Started | Status | Description |"
+                print "|---------|------|---------|--------|-------------|"
+                print ""
+            } {print}' "$session_file" > "${session_file}.tmp" && mv "${session_file}.tmp" "$session_file"
+        else
+            # Append to end
+            cat >> "$session_file" << EOF
+
+## Background Tasks
+
+| Task ID | Type | Started | Status | Description |
+|---------|------|---------|--------|-------------|
+EOF
+        fi
+    fi
+
+    # Add task row after the table header
+    awk -v tid="$task_id" -v stype="$subagent_type" -v ts="$timestamp" -v desc="$description" '
+        /^\|[-]+\|/ && in_section {
+            print
+            print "| " tid " | " stype " | " ts " | running | " desc " |"
+            next
+        }
+        /^## Background Tasks/ { in_section=1 }
+        /^## / && !/^## Background Tasks/ { in_section=0 }
+        { print }
+    ' "$session_file" > "${session_file}.tmp" && mv "${session_file}.tmp" "$session_file"
+
+    echo "Added background task: $task_id ($subagent_type)"
+}
+
+# Update background task status
+# Status: running, completed, error
+bg_task_update() {
+    local session_file="$1"
+    local task_id="$2"
+    local new_status="$3"
+
+    if [[ ! -f "$session_file" ]]; then
+        echo "ERROR: Session file not found: $session_file" >&2
+        return 1
+    fi
+
+    if ! grep -q "| $task_id |" "$session_file" 2>/dev/null; then
+        echo "WARNING: Task $task_id not found in session file" >&2
+        return 0
+    fi
+
+    # Update the status column for this task
+    sed -i '' "s/| $task_id |\\([^|]*\\)|\\([^|]*\\)| running |/| $task_id |\\1|\\2| $new_status |/" "$session_file"
+    echo "Updated task $task_id: $new_status"
+}
+
+# Remove completed and error tasks from session file
+bg_task_cleanup() {
+    local session_file="$1"
+
+    if [[ ! -f "$session_file" ]]; then
+        echo "ERROR: Session file not found: $session_file" >&2
+        return 1
+    fi
+
+    # Count tasks to remove
+    local completed_count
+    completed_count=$(_count_matches "| completed |" "$session_file")
+    local error_count
+    error_count=$(_count_matches "| error |" "$session_file")
+
+    if [[ "$completed_count" -gt 0 ]] || [[ "$error_count" -gt 0 ]]; then
+        sed -i '' '/| completed |/d' "$session_file"
+        sed -i '' '/| error |/d' "$session_file"
+        echo "Cleaned up $completed_count completed, $error_count errored tasks"
+    fi
+}
+
+# List active (running) background tasks
+bg_task_list() {
+    local session_file="$1"
+
+    if [[ ! -f "$session_file" ]]; then
+        echo "No session file"
+        return 0
+    fi
+
+    local running_tasks
+    running_tasks=$(grep "| running |" "$session_file" 2>/dev/null || true)
+
+    if [[ -n "$running_tasks" ]]; then
+        echo "$running_tasks"
+    else
+        echo "No active background tasks"
+    fi
+}
+
+# Check for active background tasks (returns 0 if tasks exist, 1 if none)
+# Useful for conditional logic in scripts
+bg_task_check() {
+    local session_file="$1"
+
+    if [[ ! -f "$session_file" ]]; then
+        return 1
+    fi
+
+    grep -q "| running |" "$session_file" 2>/dev/null
+}
+
+# Print summary of all background tasks
+bg_task_summary() {
+    local session_file="$1"
+
+    if [[ ! -f "$session_file" ]]; then
+        echo "No session file"
+        return 0
+    fi
+
+    local running
+    running=$(_count_matches "| running |" "$session_file")
+    local completed
+    completed=$(_count_matches "| completed |" "$session_file")
+    local errored
+    errored=$(_count_matches "| error |" "$session_file")
+
+    echo "Background tasks: $running running, $completed completed, $errored errored"
+}

package/pennyfarthing-dist/scripts/utils/check-status.sh

@@ -0,0 +1,251 @@
+#!/usr/bin/env zsh
+# Enhanced multi-repo git status with color and summaries
+# Usage: ./check-status.sh [repos]
+
+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"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+MAGENTA='\033[0;35m'
+NC='\033[0m'
+
+show_help() {
+    cat << 'EOF'
+Check Status - Enhanced multi-repo status
+
+Usage: ./check-status.sh [repos]
+
+Arguments:
+  repos    Which repos to check (default: all)
+           Options: api, ui, all
+
+Features:
+  - Color-coded status output
+  - Shows uncommitted changes
+  - Shows unpushed commits
+  - Shows branch sync status
+  - Summary of all repos
+  - Highlights issues requiring attention
+  - Worktree-aware
+
+Examples:
+  # Check all repos
+  ./check-status.sh
+
+  # Check specific repo
+  ./check-status.sh api
+
+EOF
+}
+
+REPOS="all"
+
+# Parse arguments
+for arg in "$@"; do
+    case $arg in
+        -h|--help)
+            show_help
+            exit 0
+            ;;
+        api|ui|all)
+            REPOS="$arg"
+            ;;
+        *)
+            echo "❌ Unknown argument: $arg"
+            show_help
+            exit 1
+            ;;
+    esac
+done
+
+# Detect if we're in a worktree
+CURRENT_DIR=$(pwd)
+if [[ "$CURRENT_DIR" == *"/worktrees/"* ]]; then
+    WORKTREE_NAME=$(echo "$CURRENT_DIR" | sed -E 's|.*/worktrees/([^/]+).*|\1|')
+    REPO_BASE="$PROJECT_ROOT/worktrees/$WORKTREE_NAME"
+    echo -e "${CYAN}📂 Worktree: $WORKTREE_NAME${NC}"
+else
+    REPO_BASE="$PROJECT_ROOT"
+    echo -e "${CYAN}📂 Main checkout${NC}"
+fi
+
+declare -a CLEAN_REPOS=()
+declare -a DIRTY_REPOS=()
+declare -a AHEAD_REPOS=()
+declare -a BEHIND_REPOS=()
+
+# Check status of a repo
+check_repo_status() {
+    local repo_path=$1
+    local repo_name=$2
+
+    if [ ! -d "$repo_path" ]; then
+        return
+    fi
+
+    cd "$repo_path"
+
+    echo ""
+    echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo -e "${BLUE}📦 $repo_name${NC}"
+    echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+    # Get current branch
+    CURRENT_BRANCH=$(git branch --show-current)
+
+    if [ -z "$CURRENT_BRANCH" ]; then
+        echo -e "   ${RED}⚠️  Detached HEAD${NC}"
+        return
+    fi
+
+    echo -e "   Branch: ${CYAN}$CURRENT_BRANCH${NC}"
+
+    # Check for uncommitted changes
+    if ! git diff-index --quiet HEAD -- 2>/dev/null; then
+        echo -e "   Status: ${YELLOW}⚠️  Uncommitted changes${NC}"
+        DIRTY_REPOS+=("$repo_name")
+
+        # Show what's changed
+        MODIFIED=$(git diff --name-only | wc -l | tr -d ' ')
+        STAGED=$(git diff --cached --name-only | wc -l | tr -d ' ')
+
+        if [ "$STAGED" -gt 0 ]; then
+            echo -e "   ${GREEN}Staged: $STAGED files${NC}"
+        fi
+        if [ "$MODIFIED" -gt 0 ]; then
+            echo -e "   ${YELLOW}Modified: $MODIFIED files${NC}"
+        fi
+
+        # Show short status
+        echo ""
+        git status --short | sed 's/^/   /'
+    else
+        echo -e "   Status: ${GREEN}✓ Clean${NC}"
+        CLEAN_REPOS+=("$repo_name")
+    fi
+
+    # Check remote tracking
+    UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "none")
+
+    if [ "$UPSTREAM" = "none" ]; then
+        echo -e "   Remote: ${YELLOW}⚠️  Not tracking remote${NC}"
+    else
+        echo -e "   Remote: ${CYAN}$UPSTREAM${NC}"
+
+        # Fetch to get latest remote info
+        git fetch origin "$CURRENT_BRANCH" --quiet 2>/dev/null || true
+
+        # Check sync status
+        LOCAL=$(git rev-parse @ 2>/dev/null)
+        REMOTE=$(git rev-parse @{u} 2>/dev/null || echo "none")
+
+        if [ "$REMOTE" = "none" ]; then
+            echo -e "   Sync:   ${YELLOW}⚠️  No remote branch${NC}"
+        elif [ "$LOCAL" = "$REMOTE" ]; then
+            echo -e "   Sync:   ${GREEN}✓ Up to date${NC}"
+        else
+            AHEAD=$(git rev-list --count @{u}..HEAD 2>/dev/null || echo "0")
+            BEHIND=$(git rev-list --count HEAD..@{u} 2>/dev/null || echo "0")
+
+            if [ "$AHEAD" -gt 0 ] && [ "$BEHIND" -gt 0 ]; then
+                echo -e "   Sync:   ${RED}⚠️  Diverged ($AHEAD ahead, $BEHIND behind)${NC}"
+            elif [ "$AHEAD" -gt 0 ]; then
+                echo -e "   Sync:   ${YELLOW}⬆️  $AHEAD commit(s) ahead${NC}"
+                AHEAD_REPOS+=("$repo_name ($AHEAD ahead)")
+            elif [ "$BEHIND" -gt 0 ]; then
+                echo -e "   Sync:   ${YELLOW}⬇️  $BEHIND commit(s) behind${NC}"
+                BEHIND_REPOS+=("$repo_name ($BEHIND behind)")
+            fi
+        fi
+    fi
+
+    # Show last commit
+    LAST_COMMIT=$(git log -1 --format="%h - %s" 2>/dev/null)
+    echo -e "   Last:   ${CYAN}$LAST_COMMIT${NC}"
+}
+
+echo ""
+echo "🔍 Checking repository status..."
+echo "   Repos: $REPOS"
+
+# Check repos
+case "$REPOS" in
+    api)
+        check_repo_status "$REPO_BASE/conductor-api" "conductor-api"
+        ;;
+    ui)
+        check_repo_status "$REPO_BASE/conductor-ui" "conductor-ui"
+        ;;
+    all)
+        check_repo_status "$REPO_BASE/conductor-api" "conductor-api"
+        check_repo_status "$REPO_BASE/conductor-ui" "conductor-ui"
+        ;;
+esac
+
+# Summary
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo "📊 Summary"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+if [ ${#CLEAN_REPOS[@]} -gt 0 ]; then
+    echo ""
+    echo -e "${GREEN}✓ Clean (${#CLEAN_REPOS[@]}):${NC}"
+    for repo in "${CLEAN_REPOS[@]}"; do
+        echo -e "   ${GREEN}✓${NC} $repo"
+    done
+fi
+
+if [ ${#DIRTY_REPOS[@]} -gt 0 ]; then
+    echo ""
+    echo -e "${YELLOW}⚠️  Uncommitted Changes (${#DIRTY_REPOS[@]}):${NC}"
+    for repo in "${DIRTY_REPOS[@]}"; do
+        echo -e "   ${YELLOW}•${NC} $repo"
+    done
+fi
+
+if [ ${#AHEAD_REPOS[@]} -gt 0 ]; then
+    echo ""
+    echo -e "${YELLOW}⬆️  Ahead of Remote (${#AHEAD_REPOS[@]}):${NC}"
+    for repo in "${AHEAD_REPOS[@]}"; do
+        echo -e "   ${YELLOW}⬆${NC} $repo"
+    done
+    echo -e "   ${CYAN}Tip: Run ./scripts/commit-and-push.sh or git push${NC}"
+fi
+
+if [ ${#BEHIND_REPOS[@]} -gt 0 ]; then
+    echo ""
+    echo -e "${YELLOW}⬇️  Behind Remote (${#BEHIND_REPOS[@]}):${NC}"
+    for repo in "${BEHIND_REPOS[@]}"; do
+        echo -e "   ${YELLOW}⬇${NC} $repo"
+    done
+    echo -e "   ${CYAN}Tip: Run git pull to update${NC}"
+fi
+
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+TOTAL_REPOS=$((${#CLEAN_REPOS[@]} + ${#DIRTY_REPOS[@]}))
+
+if [ ${#DIRTY_REPOS[@]} -eq 0 ] && [ ${#AHEAD_REPOS[@]} -eq 0 ] && [ ${#BEHIND_REPOS[@]} -eq 0 ]; then
+    echo -e "${GREEN}✅ All repositories are clean and in sync!${NC}"
+else
+    echo -e "${YELLOW}⚠️  ${#DIRTY_REPOS[@]} repo(s) with changes, ${#AHEAD_REPOS[@]} ahead, ${#BEHIND_REPOS[@]} behind${NC}"
+fi
+
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"

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

@@ -0,0 +1,136 @@
+#!/usr/bin/env zsh
+# Session checkpointing utilities
+# Dev: Fanny Price - "I was quiet, but I was not blind."
+
+# 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
+
+# Checkpoint file location (evaluated dynamically)
+_get_checkpoint_file() {
+    echo "${PROJECT_ROOT:-.}/.session/checkpoints.log"
+}
+
+# checkpoint_save LABEL DATA
+# Save a checkpoint with timestamp
+#
+# Arguments:
+#   LABEL - Identifier for this checkpoint
+#   DATA  - Data to save (string)
+#
+# Format: ISO_TIMESTAMP|LABEL|DATA
+#
+# Example:
+#   checkpoint_save "story_phase" "dev"
+#   checkpoint_save "last_file" "src/main.go:42"
+#
+checkpoint_save() {
+    local label="$1"
+    local data="$2"
+    local timestamp
+    local checkpoint_file
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    checkpoint_file=$(_get_checkpoint_file)
+
+    # Ensure directory exists
+    mkdir -p "$(dirname "$checkpoint_file")"
+
+    # Acquire exclusive lock, append checkpoint, release lock
+    if lock_acquire "$checkpoint_file" "exclusive" 5 2>/dev/null; then
+        echo "${timestamp}|${label}|${data}" >> "$checkpoint_file"
+        lock_release "$checkpoint_file"
+    else
+        # Fallback: append without lock (better than failing)
+        echo "${timestamp}|${label}|${data}" >> "$checkpoint_file"
+    fi
+}
+
+# checkpoint_restore LABEL
+# Restore the most recent checkpoint with given label
+#
+# Arguments:
+#   LABEL - Identifier to look up
+#
+# Returns:
+#   Outputs the data portion of the most recent matching checkpoint
+#   Empty if no match found
+#
+# Example:
+#   phase=$(checkpoint_restore "story_phase")
+#
+checkpoint_restore() {
+    local label="$1"
+    local checkpoint_file
+    checkpoint_file=$(_get_checkpoint_file)
+
+    if [[ ! -f "$checkpoint_file" ]]; then
+        return 0
+    fi
+
+    # Find entries with matching label, take the last one, extract data field
+    # Use || true to handle case where grep finds no matches
+    grep "|${label}|" "$checkpoint_file" 2>/dev/null | tail -1 | cut -d'|' -f3- || true
+}
+
+# checkpoint_list
+# List recent checkpoints (last 20)
+#
+# Example:
+#   checkpoint_list
+#
+checkpoint_list() {
+    local checkpoint_file
+    checkpoint_file=$(_get_checkpoint_file)
+
+    if [[ -f "$checkpoint_file" ]]; then
+        tail -20 "$checkpoint_file"
+    fi
+}
+
+# checkpoint_clear
+# Remove all checkpoints
+#
+# Example:
+#   checkpoint_clear
+#
+checkpoint_clear() {
+    local checkpoint_file
+    checkpoint_file=$(_get_checkpoint_file)
+    rm -f "$checkpoint_file"
+}
+
+# checkpoint_rotate MAX_LINES
+# Rotate checkpoint file to prevent unbounded growth
+#
+# Arguments:
+#   MAX_LINES - Maximum lines to keep (default: 1000)
+#
+# Example:
+#   checkpoint_rotate 500
+#
+checkpoint_rotate() {
+    local max_lines=${1:-1000}
+    local checkpoint_file
+    checkpoint_file=$(_get_checkpoint_file)
+
+    if [[ ! -f "$checkpoint_file" ]]; then
+        return 0
+    fi
+
+    # Acquire exclusive lock for rotation
+    if lock_acquire "$checkpoint_file" "exclusive" 5 2>/dev/null; then
+        local current_lines
+        current_lines=$(wc -l < "$checkpoint_file")
+
+        if ((current_lines > max_lines)); then
+            local temp_file
+            temp_file=$(mktemp)
+            tail -n "$max_lines" "$checkpoint_file" > "$temp_file"
+            mv "$temp_file" "$checkpoint_file"
+        fi
+        lock_release "$checkpoint_file"
+    fi
+}
+
+# Functions available when sourced