anvil-dev-framework 0.1.6

package/global/lib/anvil-state.sh

@@ -0,0 +1,435 @@
+#!/bin/bash
+# anvil-state.sh - Session state management library for Anvil framework
+# Version: 1.0.0
+#
+# This library provides functions for reading and writing anvil-state.json,
+# which tracks workflow phase, active specs/plans/issues, and cached data.
+#
+# Usage:
+#   source "path/to/anvil-state.sh"
+#   anvil_state_init
+#   anvil_state_set_phase "implement"
+#   anvil_state_set_issue "ANV-42"
+#
+# IMPORTANT: Add .claude/anvil-state.json to your project's .gitignore
+# This file contains session-specific state and should not be committed.
+
+set -euo pipefail
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+ANVIL_STATE_FILE="${ANVIL_STATE_FILE:-.claude/anvil-state.json}"
+ANVIL_STATE_VERSION="1.0"
+ANVIL_GIT_CACHE_TTL="${ANVIL_GIT_CACHE_TTL:-5}"  # seconds
+
+# ============================================================================
+# Dependency Check
+# ============================================================================
+
+# Check if jq is installed and provide helpful error message
+anvil_check_jq() {
+    if ! command -v jq &> /dev/null; then
+        echo "ERROR: jq is required but not installed." >&2
+        echo "" >&2
+        echo "Install jq:" >&2
+        echo "  macOS:   brew install jq" >&2
+        echo "  Ubuntu:  sudo apt-get install jq" >&2
+        echo "  Fedora:  sudo dnf install jq" >&2
+        echo "  Windows: choco install jq" >&2
+        echo "" >&2
+        echo "For more info: https://stedolan.github.io/jq/download/" >&2
+        return 1
+    fi
+    return 0
+}
+
+# ============================================================================
+# State File Management
+# ============================================================================
+
+# Get the state file path (creates .claude directory if needed)
+anvil_state_path() {
+    local state_dir
+    state_dir="$(dirname "$ANVIL_STATE_FILE")"
+
+    if [[ ! -d "$state_dir" ]]; then
+        mkdir -p "$state_dir"
+    fi
+
+    echo "$ANVIL_STATE_FILE"
+}
+
+# Initialize state file with default structure if it doesn't exist
+anvil_state_init() {
+    anvil_check_jq || return 1
+
+    local state_file
+    state_file="$(anvil_state_path)"
+
+    if [[ ! -f "$state_file" ]]; then
+        jq -n \
+            --arg version "$ANVIL_STATE_VERSION" \
+            --arg time "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+            '{
+                version: $version,
+                session: {
+                    phase: null,
+                    activeSpec: null,
+                    activePlan: null,
+                    activeIssue: null,
+                    lastCommand: null,
+                    lastCommandAt: null
+                },
+                cache: {
+                    git: {
+                        branch: null,
+                        dirty: null,
+                        cachedAt: null,
+                        ttlSeconds: 5
+                    }
+                },
+                meta: {
+                    createdAt: $time,
+                    updatedAt: $time
+                }
+            }' > "$state_file"
+    fi
+
+    echo "$state_file"
+}
+
+# Read the entire state file
+anvil_state_read() {
+    anvil_check_jq || return 1
+
+    local state_file
+    state_file="$(anvil_state_path)"
+
+    if [[ -f "$state_file" ]]; then
+        cat "$state_file"
+    else
+        # Return empty state structure if file doesn't exist
+        jq -n '{version: "1.0", session: {}, cache: {}}'
+    fi
+}
+
+# Read a specific field from state (dot notation: session.phase)
+anvil_state_get() {
+    local field="$1"
+    anvil_check_jq || return 1
+
+    local state_file
+    state_file="$(anvil_state_path)"
+
+    if [[ -f "$state_file" ]]; then
+        jq -r ".$field // empty" "$state_file" 2>/dev/null || echo ""
+    else
+        echo ""
+    fi
+}
+
+# ============================================================================
+# State Update Functions
+# ============================================================================
+
+# Update a single field in state (creates file if needed)
+anvil_state_set() {
+    local field="$1"
+    local value="$2"
+    anvil_check_jq || return 1
+
+    local state_file
+    state_file="$(anvil_state_init)"
+
+    local tmp_file
+    tmp_file="$(mktemp)"
+
+    # Update the field and the updatedAt timestamp
+    jq --arg value "$value" \
+       --arg time "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+       ".$field = \$value | .meta.updatedAt = \$time" \
+       "$state_file" > "$tmp_file" && mv "$tmp_file" "$state_file"
+}
+
+# Update multiple session fields at once
+anvil_state_update() {
+    local phase="${1:-}"
+    local spec="${2:-}"
+    local plan="${3:-}"
+    local issue="${4:-}"
+    local command="${5:-}"
+
+    anvil_check_jq || return 1
+
+    local state_file
+    state_file="$(anvil_state_init)"
+
+    local tmp_file
+    tmp_file="$(mktemp)"
+
+    local time
+    time="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+    # Build jq filter dynamically based on provided values
+    local jq_filter=".meta.updatedAt = \$time"
+    local jq_args=(--arg time "$time")
+
+    if [[ -n "$phase" ]]; then
+        jq_filter="$jq_filter | .session.phase = \$phase"
+        jq_args+=(--arg phase "$phase")
+    fi
+
+    if [[ -n "$spec" ]]; then
+        if [[ "$spec" == "null" || "$spec" == "clear" ]]; then
+            jq_filter="$jq_filter | .session.activeSpec = null"
+        else
+            jq_filter="$jq_filter | .session.activeSpec = \$spec"
+            jq_args+=(--arg spec "$spec")
+        fi
+    fi
+
+    if [[ -n "$plan" ]]; then
+        if [[ "$plan" == "null" || "$plan" == "clear" ]]; then
+            jq_filter="$jq_filter | .session.activePlan = null"
+        else
+            jq_filter="$jq_filter | .session.activePlan = \$plan"
+            jq_args+=(--arg plan "$plan")
+        fi
+    fi
+
+    if [[ -n "$issue" ]]; then
+        if [[ "$issue" == "null" || "$issue" == "clear" ]]; then
+            jq_filter="$jq_filter | .session.activeIssue = null"
+        else
+            jq_filter="$jq_filter | .session.activeIssue = \$issue"
+            jq_args+=(--arg issue "$issue")
+        fi
+    fi
+
+    if [[ -n "$command" ]]; then
+        jq_filter="$jq_filter | .session.lastCommand = \$command | .session.lastCommandAt = \$time"
+        jq_args+=(--arg command "$command")
+    fi
+
+    jq "${jq_args[@]}" "$jq_filter" "$state_file" > "$tmp_file" && mv "$tmp_file" "$state_file"
+}
+
+# ============================================================================
+# Convenience Functions for Common Operations
+# ============================================================================
+
+# Set current workflow phase
+anvil_state_set_phase() {
+    local phase="$1"
+    anvil_state_set "session.phase" "$phase"
+}
+
+# Set active spec ID
+anvil_state_set_spec() {
+    local spec="$1"
+    anvil_state_set "session.activeSpec" "$spec"
+}
+
+# Set active plan ID
+anvil_state_set_plan() {
+    local plan="$1"
+    anvil_state_set "session.activePlan" "$plan"
+}
+
+# Set active issue key
+anvil_state_set_issue() {
+    local issue="$1"
+    anvil_state_set "session.activeIssue" "$issue"
+}
+
+# Record command execution
+anvil_state_set_command() {
+    local command="$1"
+    local time
+    time="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+    anvil_check_jq || return 1
+
+    local state_file
+    state_file="$(anvil_state_init)"
+
+    local tmp_file
+    tmp_file="$(mktemp)"
+
+    jq --arg cmd "$command" --arg time "$time" \
+       '.session.lastCommand = $cmd | .session.lastCommandAt = $time | .meta.updatedAt = $time' \
+       "$state_file" > "$tmp_file" && mv "$tmp_file" "$state_file"
+}
+
+# Clear session state (for /orient reset)
+anvil_state_clear_session() {
+    anvil_check_jq || return 1
+
+    local state_file
+    state_file="$(anvil_state_init)"
+
+    local tmp_file
+    tmp_file="$(mktemp)"
+
+    local time
+    time="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+    jq --arg time "$time" \
+       '.session.phase = null | .session.activeSpec = null | .session.activePlan = null | .session.activeIssue = null | .meta.updatedAt = $time' \
+       "$state_file" > "$tmp_file" && mv "$tmp_file" "$state_file"
+}
+
+# ============================================================================
+# Git Cache Functions
+# ============================================================================
+
+# Check if git cache is still valid (within TTL)
+anvil_git_cache_valid() {
+    anvil_check_jq || return 1
+
+    local state_file
+    state_file="$(anvil_state_path)"
+
+    if [[ ! -f "$state_file" ]]; then
+        return 1
+    fi
+
+    local cached_at
+    cached_at="$(jq -r '.cache.git.cachedAt // empty' "$state_file" 2>/dev/null)"
+
+    if [[ -z "$cached_at" ]]; then
+        return 1
+    fi
+
+    local ttl
+    ttl="$(jq -r '.cache.git.ttlSeconds // 5' "$state_file" 2>/dev/null)"
+
+    # Convert ISO timestamp to epoch seconds
+    local cached_epoch
+    local current_epoch
+
+    if [[ "$(uname)" == "Darwin" ]]; then
+        # macOS: Use TZ=UTC to ensure proper UTC parsing
+        cached_epoch="$(TZ=UTC date -j -f "%Y-%m-%dT%H:%M:%SZ" "$cached_at" "+%s" 2>/dev/null || echo 0)"
+    else
+        # Linux: date -d handles ISO format natively with UTC suffix
+        cached_epoch="$(date -d "$cached_at" "+%s" 2>/dev/null || echo 0)"
+    fi
+    current_epoch="$(date -u "+%s")"
+
+    local age=$((current_epoch - cached_epoch))
+
+    if [[ $age -lt $ttl ]]; then
+        return 0  # Cache is valid
+    else
+        return 1  # Cache expired
+    fi
+}
+
+# Get git branch (from cache if valid, otherwise fresh)
+anvil_git_branch() {
+    # Try cache first
+    if anvil_git_cache_valid; then
+        local cached_branch
+        cached_branch="$(anvil_state_get 'cache.git.branch')"
+        if [[ -n "$cached_branch" ]]; then
+            echo "$cached_branch"
+            return 0
+        fi
+    fi
+
+    # Get fresh value
+    local branch
+    branch="$(git branch --show-current 2>/dev/null || echo "")"
+
+    # Update cache
+    anvil_git_cache_update "$branch"
+
+    echo "$branch"
+}
+
+# Update git cache with fresh values
+anvil_git_cache_update() {
+    local branch="${1:-}"
+
+    anvil_check_jq || return 1
+
+    # Get branch if not provided
+    if [[ -z "$branch" ]]; then
+        branch="$(git branch --show-current 2>/dev/null || echo "")"
+    fi
+
+    # Check if working tree is dirty
+    local dirty="false"
+    if [[ -n "$(git status --porcelain 2>/dev/null)" ]]; then
+        dirty="true"
+    fi
+
+    local state_file
+    state_file="$(anvil_state_init)"
+
+    local tmp_file
+    tmp_file="$(mktemp)"
+
+    local time
+    time="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+    jq --arg branch "$branch" \
+       --argjson dirty "$dirty" \
+       --arg time "$time" \
+       --argjson ttl "$ANVIL_GIT_CACHE_TTL" \
+       '.cache.git.branch = $branch | .cache.git.dirty = $dirty | .cache.git.cachedAt = $time | .cache.git.ttlSeconds = $ttl | .meta.updatedAt = $time' \
+       "$state_file" > "$tmp_file" && mv "$tmp_file" "$state_file"
+}
+
+# ============================================================================
+# Utility Functions
+# ============================================================================
+
+# Pretty print the current state (for debugging)
+anvil_state_debug() {
+    anvil_check_jq || return 1
+
+    local state_file
+    state_file="$(anvil_state_path)"
+
+    if [[ -f "$state_file" ]]; then
+        echo "=== Anvil State ($state_file) ==="
+        jq '.' "$state_file"
+    else
+        echo "State file does not exist: $state_file"
+    fi
+}
+
+# Check if state file exists and is valid JSON
+anvil_state_valid() {
+    local state_file
+    state_file="$(anvil_state_path)"
+
+    if [[ ! -f "$state_file" ]]; then
+        return 1
+    fi
+
+    if jq empty "$state_file" 2>/dev/null; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+# Repair corrupted state file by recreating it
+anvil_state_repair() {
+    local state_file
+    state_file="$(anvil_state_path)"
+
+    if [[ -f "$state_file" ]]; then
+        local backup="${state_file}.bak"
+        mv "$state_file" "$backup"
+        echo "Backed up corrupted state to: $backup" >&2
+    fi
+
+    anvil_state_init
+    echo "Created fresh state file: $state_file" >&2
+}