claude-autopm 2.8.2 → 2.8.4

package/packages/plugin-core/rules/use-ast-grep.md

@@ -0,0 +1,113 @@
+# AST-Grep Integration Protocol for Cursor Agent
+
+## When to Use AST-Grep
+
+Use `ast-grep` (if installed) instead of plain regex or text search when:
+
+- **Structural code patterns** are involved (e.g., finding all function calls, class definitions, or method implementations)
+- **Language-aware refactoring** is required (e.g., renaming variables, updating function signatures, or changing imports)
+- **Complex code analysis** is needed (e.g., finding all usages of a pattern across different syntactic contexts)
+- **Cross-language searches** are necessary (e.g., working with both Ruby and TypeScript in a monorepo)
+- **Semantic code understanding** is important (e.g., finding patterns based on code structure, not just text)
+
+## AST-Grep Command Patterns
+
+### Basic Search Template
+
+```sh
+ast-grep --pattern '$PATTERN' --lang $LANGUAGE $PATH
+```
+
+### Common Use Cases
+
+- **Find function calls:**
+  `ast-grep --pattern 'functionName($$$)' --lang javascript .`
+- **Find class definitions:**
+  `ast-grep --pattern 'class $NAME { $$$ }' --lang typescript .`
+- **Find variable assignments:**
+  `ast-grep --pattern '$VAR = $$$' --lang ruby .`
+- **Find import statements:**
+  `ast-grep --pattern 'import { $$$ } from "$MODULE"' --lang javascript .`
+- **Find method calls on objects:**
+  `ast-grep --pattern '$OBJ.$METHOD($$$)' --lang typescript .`
+- **Find React hooks:**
+  `ast-grep --pattern 'const [$STATE, $SETTER] = useState($$$)' --lang typescript .`
+- **Find Ruby class definitions:**
+  `ast-grep --pattern 'class $NAME < $$$; $$$; end' --lang ruby .`
+
+## Pattern Syntax Reference
+
+- `$VAR` — matches any single node and captures it
+- `$$$` — matches zero or more nodes (wildcard)
+- `$$` — matches one or more nodes
+- Literal code — matches exactly as written
+
+## Supported Languages
+
+- javascript, typescript, ruby, python, go, rust, java, c, cpp, html, css, yaml, json, and more
+
+## Integration Workflow
+
+### Before using ast-grep
+
+1. **Check if ast-grep is installed:**
+   If not, skip and fall back to regex/semantic search.
+
+   ```sh
+   command -v ast-grep >/dev/null 2>&1 || echo "ast-grep not installed, skipping AST search"
+   ```
+
+2. **Identify** if the task involves structural code patterns or language-aware refactoring.
+3. **Determine** the appropriate language(s) to search.
+4. **Construct** the pattern using ast-grep syntax.
+5. **Run** ast-grep to gather precise structural information.
+6. **Use** results to inform code edits, refactoring, or further analysis.
+
+### Example Workflow
+
+When asked to "find all Ruby service objects that call `perform`":
+
+1. **Check for ast-grep:**
+
+   ```sh
+   command -v ast-grep >/dev/null 2>&1 && ast-grep --pattern 'perform($$$)' --lang ruby app/services/
+   ```
+
+2. **Analyze** results structurally.
+3. **Use** codebase semantic search for additional context if needed.
+4. **Make** informed edits based on structural understanding.
+
+### Combine ast-grep with Internal Tools
+
+- **codebase_search** for semantic context and documentation
+- **read_file** for examining specific files found by ast-grep
+- **edit_file** for making precise, context-aware code changes
+
+### Advanced Usage
+
+- **JSON output for programmatic processing:**
+  `ast-grep --pattern '$PATTERN' --lang $LANG $PATH --json`
+- **Replace patterns:**
+  `ast-grep --pattern '$OLD_PATTERN' --rewrite '$NEW_PATTERN' --lang $LANG $PATH`
+- **Interactive mode:**
+  `ast-grep --pattern '$PATTERN' --lang $LANG $PATH --interactive`
+
+## Key Benefits Over Regex
+
+1. **Language-aware** — understands syntax and semantics
+2. **Structural matching** — finds patterns regardless of formatting
+3. **Cross-language** — works consistently across different languages
+4. **Precise refactoring** — makes structural changes safely
+5. **Context-aware** — understands code hierarchy and scope
+
+## Decision Matrix: When to Use Each Tool
+
+| Task Type                | Tool Choice          | Reason                        |
+|--------------------------|----------------------|-------------------------------|
+| Find text patterns       | grep_search          | Simple text matching          |
+| Find code structures     | ast-grep             | Syntax-aware search           |
+| Understand semantics     | codebase_search      | AI-powered context            |
+| Make edits               | edit_file            | Precise file editing          |
+| Structural refactoring   | ast-grep + edit_file | Structure + precision         |
+
+**Always prefer ast-grep for code structure analysis over regex-based approaches, but only if it is installed and available.**

package/packages/plugin-core/scripts/lib/datetime-utils.sh

@@ -0,0 +1,254 @@
+#!/bin/bash
+# DateTime Utility Library
+# Provides consistent datetime operations across all scripts
+
+set -euo pipefail
+
+# Load dependencies
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/logging-utils.sh"
+
+# Get current datetime in ISO 8601 format (UTC)
+get_current_datetime() {
+    date -u +"%Y-%m-%dT%H:%M:%SZ"
+}
+
+# Get current date only (YYYY-MM-DD)
+get_current_date() {
+    date -u +"%Y-%m-%d"
+}
+
+# Get current timestamp (Unix epoch)
+get_current_timestamp() {
+    date +%s
+}
+
+# Convert ISO datetime to Unix timestamp
+datetime_to_timestamp() {
+    local iso_datetime="$1"
+
+    log_function_entry "datetime_to_timestamp" "$iso_datetime"
+
+    local timestamp
+    if command -v gdate >/dev/null 2>&1; then
+        # macOS with GNU date installed
+        timestamp=$(gdate -d "$iso_datetime" +%s 2>/dev/null)
+    else
+        # Linux date or BSD date
+        timestamp=$(date -d "$iso_datetime" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%SZ" "$iso_datetime" +%s 2>/dev/null)
+    fi
+
+    if [[ -z "$timestamp" ]]; then
+        log_error "Failed to parse datetime: $iso_datetime"
+        return 1
+    fi
+
+    log_function_exit "datetime_to_timestamp"
+    echo "$timestamp"
+    return 0
+}
+
+# Convert Unix timestamp to ISO datetime
+timestamp_to_datetime() {
+    local timestamp="$1"
+
+    log_function_entry "timestamp_to_datetime" "$timestamp"
+
+    local iso_datetime
+    iso_datetime=$(date -u -d "@$timestamp" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -r "$timestamp" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null)
+
+    if [[ -z "$iso_datetime" ]]; then
+        log_error "Failed to convert timestamp: $timestamp"
+        return 1
+    fi
+
+    log_function_exit "timestamp_to_datetime"
+    echo "$iso_datetime"
+    return 0
+}
+
+# Calculate time difference in seconds between two ISO datetimes
+datetime_diff_seconds() {
+    local datetime1="$1"
+    local datetime2="$2"
+
+    log_function_entry "datetime_diff_seconds" "$datetime1" "$datetime2"
+
+    local timestamp1 timestamp2
+    timestamp1=$(datetime_to_timestamp "$datetime1") || return 1
+    timestamp2=$(datetime_to_timestamp "$datetime2") || return 1
+
+    local diff
+    diff=$((timestamp2 - timestamp1))
+
+    log_function_exit "datetime_diff_seconds"
+    echo "$diff"
+    return 0
+}
+
+# Calculate time difference in minutes
+datetime_diff_minutes() {
+    local datetime1="$1"
+    local datetime2="$2"
+
+    local diff_seconds
+    diff_seconds=$(datetime_diff_seconds "$datetime1" "$datetime2") || return 1
+
+    local diff_minutes
+    diff_minutes=$((diff_seconds / 60))
+
+    echo "$diff_minutes"
+    return 0
+}
+
+# Calculate time difference in hours
+datetime_diff_hours() {
+    local datetime1="$1"
+    local datetime2="$2"
+
+    local diff_seconds
+    diff_seconds=$(datetime_diff_seconds "$datetime1" "$datetime2") || return 1
+
+    local diff_hours
+    diff_hours=$((diff_seconds / 3600))
+
+    echo "$diff_hours"
+    return 0
+}
+
+# Calculate time difference in days
+datetime_diff_days() {
+    local datetime1="$1"
+    local datetime2="$2"
+
+    local diff_seconds
+    diff_seconds=$(datetime_diff_seconds "$datetime1" "$datetime2") || return 1
+
+    local diff_days
+    diff_days=$((diff_seconds / 86400))
+
+    echo "$diff_days"
+    return 0
+}
+
+# Check if datetime1 is before datetime2
+datetime_is_before() {
+    local datetime1="$1"
+    local datetime2="$2"
+
+    local diff
+    diff=$(datetime_diff_seconds "$datetime1" "$datetime2") || return 1
+
+    [[ "$diff" -gt 0 ]]
+}
+
+# Check if datetime1 is after datetime2
+datetime_is_after() {
+    local datetime1="$1"
+    local datetime2="$2"
+
+    local diff
+    diff=$(datetime_diff_seconds "$datetime1" "$datetime2") || return 1
+
+    [[ "$diff" -lt 0 ]]
+}
+
+# Format time duration in human-readable format
+format_duration() {
+    local seconds="$1"
+
+    log_function_entry "format_duration" "$seconds"
+
+    if [[ "$seconds" -lt 60 ]]; then
+        echo "${seconds}s"
+    elif [[ "$seconds" -lt 3600 ]]; then
+        local minutes=$((seconds / 60))
+        local remaining_seconds=$((seconds % 60))
+        if [[ "$remaining_seconds" -eq 0 ]]; then
+            echo "${minutes}m"
+        else
+            echo "${minutes}m ${remaining_seconds}s"
+        fi
+    elif [[ "$seconds" -lt 86400 ]]; then
+        local hours=$((seconds / 3600))
+        local remaining_minutes=$(((seconds % 3600) / 60))
+        if [[ "$remaining_minutes" -eq 0 ]]; then
+            echo "${hours}h"
+        else
+            echo "${hours}h ${remaining_minutes}m"
+        fi
+    else
+        local days=$((seconds / 86400))
+        local remaining_hours=$(((seconds % 86400) / 3600))
+        if [[ "$remaining_hours" -eq 0 ]]; then
+            echo "${days}d"
+        else
+            echo "${days}d ${remaining_hours}h"
+        fi
+    fi
+
+    log_function_exit "format_duration"
+}
+
+# Get human-readable time ago (e.g., "2 hours ago")
+time_ago() {
+    local past_datetime="$1"
+    local current_datetime="${2:-$(get_current_datetime)}"
+
+    log_function_entry "time_ago" "$past_datetime" "$current_datetime"
+
+    local diff_seconds
+    diff_seconds=$(datetime_diff_seconds "$past_datetime" "$current_datetime") || return 1
+
+    if [[ "$diff_seconds" -lt 0 ]]; then
+        echo "in the future"
+        return 0
+    fi
+
+    local duration
+    duration=$(format_duration "$diff_seconds")
+
+    echo "$duration ago"
+    log_function_exit "time_ago"
+}
+
+# Validate ISO datetime format
+validate_datetime() {
+    local datetime="$1"
+
+    log_function_entry "validate_datetime" "$datetime"
+
+    # Check basic format: YYYY-MM-DDTHH:MM:SSZ
+    if [[ ! "$datetime" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$ ]]; then
+        log_error "Invalid datetime format: $datetime (expected: YYYY-MM-DDTHH:MM:SSZ)"
+        return 1
+    fi
+
+    # Try to parse it to validate
+    local timestamp
+    timestamp=$(datetime_to_timestamp "$datetime") || return 1
+
+    log_debug "Datetime validation passed: $datetime"
+    log_function_exit "validate_datetime"
+    return 0
+}
+
+# Get datetime for timezone
+get_datetime_in_timezone() {
+    local timezone="$1"
+
+    log_function_entry "get_datetime_in_timezone" "$timezone"
+
+    local datetime
+    if command -v gdate >/dev/null 2>&1; then
+        # macOS with GNU date
+        datetime=$(TZ="$timezone" gdate +"%Y-%m-%dT%H:%M:%S%z")
+    else
+        # Linux date
+        datetime=$(TZ="$timezone" date +"%Y-%m-%dT%H:%M:%S%z")
+    fi
+
+    log_function_exit "get_datetime_in_timezone"
+    echo "$datetime"
+    return 0
+}

package/packages/plugin-core/scripts/lib/frontmatter-utils.sh

@@ -0,0 +1,294 @@
+#!/bin/bash
+# Frontmatter Utility Library
+# Provides functions for YAML frontmatter manipulation in markdown files
+
+set -euo pipefail
+
+# Load dependencies
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/logging-utils.sh"
+source "${SCRIPT_DIR}/datetime-utils.sh"
+
+# Escape special characters for use in sed pattern
+sed_escape_pattern() {
+    local str="$1"
+    # Escape characters that have special meaning in sed patterns: . * [ ] ^ $ \ /
+    printf '%s\n' "$str" | sed 's/[]\/$*.^[]/\\&/g'
+}
+
+# Escape special characters for use in sed replacement
+sed_escape_replacement() {
+    local str="$1"
+    # Escape backslashes first, then other special characters
+    # This prevents double-escaping issues
+    printf '%s\n' "$str" | sed 's/\\/\\\\/g; s/&/\\&/g; s/|/\\|/g'
+}
+
+# Update or add a field in frontmatter
+update_frontmatter_field() {
+    local file_path="$1"
+    local field_name="$2"
+    local field_value="$3"
+
+    log_function_entry "update_frontmatter_field" "$file_path" "$field_name" "$field_value"
+
+    if [[ ! -f "$file_path" ]]; then
+        log_error "File not found: $file_path"
+        return 1
+    fi
+
+    # Create backup
+    cp "$file_path" "${file_path}.bak"
+
+    # Escape field name and value for safe use in sed
+    local escaped_field_name
+    local escaped_field_value
+    escaped_field_name=$(sed_escape_pattern "$field_name")
+    escaped_field_value=$(sed_escape_replacement "$field_value")
+
+    # Check if field exists
+    if grep -q "^${field_name}:" "$file_path"; then
+        # Update existing field - delete old line and insert new one
+        # This approach avoids sed replacement string escaping issues
+        grep -v "^${escaped_field_name}:" "$file_path" > "${file_path}.tmp"
+        {
+            head -1 "${file_path}.tmp"  # First --- line
+            printf '%s: %s\n' "$field_name" "$field_value"  # New field value
+            tail -n +2 "${file_path}.tmp"  # Rest of file
+        } > "${file_path}.tmp2" && mv "${file_path}.tmp2" "$file_path"
+        rm -f "${file_path}.tmp"
+        log_debug "Updated existing field: $field_name"
+    else
+        # Add new field after the first line of frontmatter (after opening ---)
+        # Write the new line directly to avoid variable expansion issues
+        {
+            head -1 "$file_path"  # First --- line
+            printf '%s: %s\n' "$field_name" "$field_value"  # New field (preserves all chars)
+            tail -n +2 "$file_path"  # Rest of file
+        } > "${file_path}.tmp" && mv "${file_path}.tmp" "$file_path"
+        log_debug "Added new field: $field_name"
+    fi
+
+    # Remove backup if operation successful
+    rm -f "${file_path}.bak"
+
+    log_function_exit "update_frontmatter_field"
+    return 0
+}
+
+# Get a field value from frontmatter
+get_frontmatter_field() {
+    local file_path="$1"
+    local field_name="$2"
+
+    log_function_entry "get_frontmatter_field" "$file_path" "$field_name"
+
+    if [[ ! -f "$file_path" ]]; then
+        log_error "File not found: $file_path"
+        log_function_exit "get_frontmatter_field" 1
+        return 1
+    fi
+
+    # Escape field name for safe use in patterns
+    local escaped_field_name
+    escaped_field_name=$(sed_escape_pattern "$field_name")
+
+    local field_value
+    # Use | delimiter to avoid conflicts with / in values
+    # Only remove the field name, colon, and exactly one space (YAML format)
+    field_value=$(grep "^${field_name}:" "$file_path" | sed "s|^${escaped_field_name}: ||" | head -1)
+
+    log_debug "Retrieved field $field_name: '$field_value'"
+    log_function_exit "get_frontmatter_field"
+
+    echo "$field_value"
+    return 0
+}
+
+# Strip frontmatter from file and output content only
+strip_frontmatter() {
+    local input_file="$1"
+    local output_file="$2"
+
+    log_function_entry "strip_frontmatter" "$input_file" "$output_file"
+
+    if [[ ! -f "$input_file" ]]; then
+        log_error "Input file not found: $input_file"
+        return 1
+    fi
+
+    # Remove frontmatter (everything between first two --- lines)
+    sed '1,/^---$/d; 1,/^---$/d' "$input_file" > "$output_file"
+
+    log_debug "Stripped frontmatter from $input_file to $output_file"
+    log_function_exit "strip_frontmatter"
+    return 0
+}
+
+# Update multiple frontmatter fields with current timestamp
+update_frontmatter_with_timestamp() {
+    local file_path="$1"
+    shift
+    local current_timestamp
+    current_timestamp=$(get_current_datetime)
+
+    log_function_entry "update_frontmatter_with_timestamp" "$file_path" "$*"
+
+    # Update each field=value pair provided
+    while [[ $# -gt 0 ]]; do
+        local field_assignment="$1"
+        local field_name="${field_assignment%%=*}"
+        local field_value="${field_assignment#*=}"
+
+        # Special handling for timestamp fields
+        if [[ "$field_value" == "NOW" ]]; then
+            field_value="$current_timestamp"
+        fi
+
+        update_frontmatter_field "$file_path" "$field_name" "$field_value"
+        shift
+    done
+
+    # Always update the 'updated' field with current timestamp
+    update_frontmatter_field "$file_path" "updated" "$current_timestamp"
+
+    log_function_exit "update_frontmatter_with_timestamp"
+    return 0
+}
+
+# Validate frontmatter structure
+validate_frontmatter() {
+    local file_path="$1"
+
+    log_function_entry "validate_frontmatter" "$file_path"
+
+    if [[ ! -f "$file_path" ]]; then
+        log_error "File not found: $file_path"
+        return 1
+    fi
+
+    # Check if file starts with frontmatter
+    if ! head -1 "$file_path" | grep -q "^---$"; then
+        log_error "File does not start with frontmatter: $file_path"
+        return 1
+    fi
+
+    # Check if frontmatter is properly closed
+    if ! sed -n '2,/^---$/p' "$file_path" | tail -1 | grep -q "^---$"; then
+        log_error "Frontmatter not properly closed: $file_path"
+        return 1
+    fi
+
+    log_debug "Frontmatter validation passed: $file_path"
+    log_function_exit "validate_frontmatter"
+    return 0
+}
+
+# Extract frontmatter only (without content)
+extract_frontmatter() {
+    local input_file="$1"
+    local output_file="$2"
+
+    log_function_entry "extract_frontmatter" "$input_file" "$output_file"
+
+    if [[ ! -f "$input_file" ]]; then
+        log_error "Input file not found: $input_file"
+        return 1
+    fi
+
+    # Extract everything from first --- to second ---
+    sed -n '1,/^---$/p; /^---$/q' "$input_file" > "$output_file"
+
+    log_debug "Extracted frontmatter from $input_file to $output_file"
+    log_function_exit "extract_frontmatter"
+    return 0
+}
+
+# Get all frontmatter fields as key=value pairs
+get_all_frontmatter_fields() {
+    local file_path="$1"
+
+    log_function_entry "get_all_frontmatter_fields" "$file_path"
+
+    if [[ ! -f "$file_path" ]]; then
+        log_error "File not found: $file_path"
+        return 1
+    fi
+
+    # Extract frontmatter and parse key-value pairs
+    sed -n '2,/^---$/p' "$file_path" | sed '/^---$/d' | grep -E "^[^:]+:" | while IFS=': ' read -r key value; do
+        echo "${key}=${value}"
+    done
+
+    log_function_exit "get_all_frontmatter_fields"
+    return 0
+}
+
+# Calculate completion percentage for epic based on task statuses
+calculate_epic_progress() {
+    local epic_dir="$1"
+
+    log_function_entry "calculate_epic_progress" "$epic_dir"
+
+    if [[ ! -d "$epic_dir" ]]; then
+        log_error "Epic directory not found: $epic_dir"
+        return 1
+    fi
+
+    local total_tasks=0
+    local completed_tasks=0
+
+    # Count all task files (numbered .md files)
+    for task_file in "$epic_dir"/[0-9]*.md; do
+        [[ -f "$task_file" ]] || continue
+        total_tasks=$((total_tasks + 1))
+
+        # Check if task is completed
+        local status
+        status=$(get_frontmatter_field "$task_file" "status" 2>/dev/null || echo "open")
+        if [[ "$status" == "closed" || "$status" == "completed" ]]; then
+            completed_tasks=$((completed_tasks + 1))
+        fi
+    done
+
+    if [[ "$total_tasks" -eq 0 ]]; then
+        echo "0"
+        log_function_exit "calculate_epic_progress"
+        return 0
+    fi
+
+    # Calculate percentage
+    local progress
+    progress=$(( (completed_tasks * 100) / total_tasks ))
+
+    log_debug "Epic progress: $completed_tasks/$total_tasks = $progress%"
+    log_function_exit "calculate_epic_progress"
+
+    echo "$progress"
+    return 0
+}
+
+# Update epic progress based on task completion
+update_epic_progress() {
+    local epic_file="$1"
+    local epic_dir="$(dirname "$epic_file")"
+
+    log_function_entry "update_epic_progress" "$epic_file"
+
+    local current_progress
+    current_progress=$(calculate_epic_progress "$epic_dir")
+
+    # Update epic frontmatter with calculated progress
+    update_frontmatter_field "$epic_file" "progress" "${current_progress}%"
+
+    # Update status based on progress
+    if [[ "$current_progress" -eq 100 ]]; then
+        update_frontmatter_field "$epic_file" "status" "completed"
+    elif [[ "$current_progress" -gt 0 ]]; then
+        update_frontmatter_field "$epic_file" "status" "in-progress"
+    fi
+
+    log_success "Updated epic progress to ${current_progress}%"
+    log_function_exit "update_epic_progress"
+    return 0
+}