@stackmemoryai/stackmemory 0.3.16 → 0.3.18

package/scripts/git-hooks/README.md

@@ -0,0 +1,310 @@
+# StackMemory Git Hooks
+
+Automated git workflow integration that syncs tasks, validates code, and maintains project context across branches.
+
+## 🚀 Quick Start
+
+```bash
+# Install all hooks
+./scripts/install-stackmemory-hooks.sh
+
+# Check status
+./scripts/install-stackmemory-hooks.sh status
+
+# Selective installation
+./scripts/install-stackmemory-hooks.sh --selective
+```
+
+## 📋 Available Hooks
+
+### Pre-Commit Hook
+**File**: `pre-commit-stackmemory.sh`
+
+**What it does**:
+- ✅ Validates task states and warns about blocked tasks
+- ✅ Runs lint checks (npm/cargo)
+- ✅ Performs type checking (TypeScript/Python/Rust)
+- ✅ Saves StackMemory context before commit
+- ⚠️ Optionally runs critical tests
+
+**Configuration**:
+```bash
+# In the hook file, modify these variables:
+VALIDATE_TASKS=true           # Check task states
+VALIDATE_LINT=true           # Run linting
+VALIDATE_TYPES=true          # Run type checking
+VALIDATE_TESTS_CRITICAL=false # Run critical tests
+AUTO_UPDATE_TASKS=true       # Auto-update task progress
+```
+
+### Post-Commit Hook
+**File**: `post-commit-stackmemory.sh`
+
+**What it does**:
+- 📝 Parses commit messages for task completion indicators
+- ✅ Auto-updates task status based on commit content
+- 🎯 Creates completion frames for significant commits
+- 📊 Records commit metrics in StackMemory
+- 🔄 Syncs with Linear when configured
+
+**Configuration**:
+```bash
+AUTO_UPDATE_TASKS=true       # Auto-update based on commits
+SYNC_LINEAR=true            # Sync with Linear issues
+PARSE_COMMIT_MESSAGES=true  # Parse commit messages
+UPDATE_TASK_PROGRESS=true   # Update task progress
+CREATE_COMPLETION_FRAMES=true # Create completion frames
+```
+
+### Post-Checkout Hook (Branch Context)
+**File**: `post-checkout-stackmemory.sh`
+
+**What it does**:
+- 🌿 Detects branch switches
+- 💾 Saves context when leaving a branch
+- 📂 Loads context when entering a branch
+- 🏷️ Provides branch-specific guidance
+- 🔍 Filters tasks by branch prefix
+
+**Configuration**:
+```bash
+BRANCH_ISOLATION_ENABLED=true  # Enable branch isolation
+AUTO_SWITCH_CONTEXT=true      # Auto-load branch context
+PRESERVE_CONTEXT=true         # Save context on branch switch
+BRANCH_PREFIX_FILTERING=true  # Filter tasks by branch name
+```
+
+## 🎯 Workflow Examples
+
+### Feature Development
+```bash
+# 1. Create feature branch
+git checkout -b feature/STA-123-user-auth
+# → Hook creates initial context frame
+# → Shows feature development guidance
+
+# 2. Start working
+stackmemory task add "Implement user authentication" --priority high
+stackmemory start_frame --name "User auth implementation"
+
+# 3. Make commits
+git add .
+git commit -m "feat: implement JWT authentication"
+# → Hook parses commit for completion indicators
+# → Auto-updates task progress
+# → Creates completion frame
+
+# 4. Switch branches
+git checkout main
+# → Hook saves feature branch context
+# → Loads main branch context
+```
+
+### Bug Fix Workflow
+```bash
+# 1. Create bugfix branch
+git checkout -b bugfix/fix-login-issue
+# → Hook detects bugfix branch type
+# → Suggests creating high-priority bug task
+
+# 2. Work on fix
+stackmemory task add "Fix login validation bug" --priority critical
+git add .
+git commit -m "fix: resolve login validation for empty emails"
+# → Hook detects "fix" keyword
+# → Marks related tasks as completed
+# → Syncs with Linear if configured
+```
+
+## ⚙️ Configuration Options
+
+### Environment Variables
+```bash
+# Disable specific hook features
+export STACKMEMORY_HOOKS_DISABLED=true    # Disable all hooks
+export STACKMEMORY_NO_LINEAR_SYNC=true    # Disable Linear sync
+export STACKMEMORY_NO_AUTO_TASKS=true     # Disable auto task updates
+
+# Hook-specific settings
+export STACKMEMORY_LINT_DISABLED=true     # Skip lint checks
+export STACKMEMORY_TYPE_CHECK_DISABLED=true # Skip type checking
+```
+
+### Project-Specific Configuration
+Create `.stackmemory/hooks.config` in your project:
+```json
+{
+  "enabled": true,
+  "preCommit": {
+    "validateTasks": true,
+    "validateLint": true,
+    "validateTypes": true,
+    "runCriticalTests": false
+  },
+  "postCommit": {
+    "autoUpdateTasks": true,
+    "syncLinear": true,
+    "createCompletionFrames": true
+  },
+  "branchContext": {
+    "isolationEnabled": true,
+    "autoSwitchContext": true,
+    "preserveContext": true
+  },
+  "commitParsing": {
+    "completionKeywords": ["complete", "done", "finish", "resolve"],
+    "taskIdPatterns": ["STA-\\d+", "TASK-\\d+", "tsk-[a-zA-Z0-9]+"]
+  }
+}
+```
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+**Hook not executing**:
+```bash
+# Check if hooks are executable
+ls -la .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+
+# Check hook status
+./scripts/install-stackmemory-hooks.sh status
+```
+
+**StackMemory not found**:
+```bash
+# Install StackMemory CLI
+npm install -g @stackmemoryai/stackmemory
+
+# Initialize in project
+stackmemory init
+```
+
+**Linear sync failing**:
+```bash
+# Check Linear auth
+stackmemory linear status
+
+# Setup Linear if needed
+stackmemory linear setup
+```
+
+**Lint/type check failures**:
+```bash
+# Check if tools are installed
+npm run lint   # or cargo clippy
+npm run typecheck  # or tsc --noEmit
+
+# Disable in hook if not needed
+# Edit hook file and set VALIDATE_LINT=false
+```
+
+### Debug Mode
+Enable debug output in hooks:
+```bash
+# Add to top of hook files
+set -x  # Enable debug output
+```
+
+### Skip Hooks Temporarily
+```bash
+# Skip all hooks for one commit
+git commit -m "message" --no-verify
+
+# Skip specific hook checks
+STACKMEMORY_LINT_DISABLED=true git commit -m "message"
+```
+
+## 📊 Integration Details
+
+### Commit Message Parsing
+The hooks automatically detect these patterns:
+
+**Task Completion**:
+- `complete`, `done`, `finish`, `resolve`, `close`
+- Example: `"feat: complete user authentication module"`
+
+**Task Types**:
+- `feat`/`feature` → Feature development
+- `fix`/`bugfix` → Bug fixing
+- `refactor` → Code refactoring
+- `test` → Testing work
+
+**Task IDs**:
+- `STA-123` → Linear issue reference
+- `tsk-abc123` → StackMemory task ID
+- `#123` → Generic issue reference
+
+### Linear Integration
+When Linear is configured:
+- Commit references to `STA-123` automatically update Linear issues
+- Task completion syncs status changes
+- Comments are added to Linear issues with commit details
+
+### Branch Context Isolation
+- Each branch maintains separate task context
+- Context is automatically saved/restored on branch switches
+- Branch naming conventions trigger specific workflows:
+  - `feature/` → Feature development guidance
+  - `bugfix/` → Bug fix workflow
+  - `hotfix/` → Critical fix workflow
+
+## 🎛️ Customization
+
+### Adding Custom Validation
+Edit `pre-commit-stackmemory.sh` and add custom functions:
+
+```bash
+# Add custom validation
+validate_custom_rules() {
+    log_info "Running custom validation..."
+    
+    # Your custom validation here
+    if ! my_custom_check; then
+        log_error "Custom validation failed"
+        return 1
+    fi
+    
+    return 0
+}
+
+# Add to main execution pipeline
+if ! validate_custom_rules; then
+    failed=true
+fi
+```
+
+### Custom Commit Parsing
+Edit `post-commit-stackmemory.sh` to add custom commit message parsing:
+
+```bash
+parse_commit_message() {
+    local commit_msg="$1"
+    
+    # Add your custom patterns
+    if echo "$commit_msg" | grep -iE "deploy|release"; then
+        task_actions="${task_actions}deployment,"
+    fi
+    
+    # Continue with existing logic...
+}
+```
+
+## 🔄 Updating Hooks
+
+```bash
+# Reinstall hooks (preserves configuration)
+./scripts/install-stackmemory-hooks.sh --force
+
+# Update specific hook
+cp scripts/git-hooks/pre-commit-stackmemory.sh .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+## 📚 Related Documentation
+
+- [StackMemory CLI Reference](../CLI.md)
+- [Linear Integration Guide](../LINEAR.md)
+- [Task Management Workflows](../TASKS.md)
+- [Git Workflow Best Practices](../GIT_WORKFLOW.md)

package/scripts/git-hooks/branch-context-manager.sh

@@ -0,0 +1,342 @@
+#!/bin/bash
+# StackMemory Branch Context Manager
+# Manages task isolation and context switching between branches
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+log_info() {
+    echo -e "${BLUE}ℹ️  $1${NC}"
+}
+
+log_success() {
+    echo -e "${GREEN}✅ $1${NC}"
+}
+
+log_warning() {
+    echo -e "${YELLOW}⚠️  $1${NC}"
+}
+
+log_error() {
+    echo -e "${RED}❌ $1${NC}"
+}
+
+# Configuration
+BRANCH_ISOLATION_ENABLED=true
+AUTO_SWITCH_CONTEXT=true
+PRESERVE_CONTEXT=true
+BRANCH_PREFIX_FILTERING=true
+
+# Get current branch
+get_current_branch() {
+    git branch --show-current 2>/dev/null || echo "HEAD"
+}
+
+# Get previous branch from reflog
+get_previous_branch() {
+    git reflog --no-merges -1 --format='%gd %gs' | grep 'checkout:' | sed 's/.*checkout: moving from \([^ ]*\) to.*/\1/' || echo ""
+}
+
+# Check if StackMemory is available
+check_stackmemory() {
+    if ! command -v stackmemory >/dev/null 2>&1; then
+        log_warning "StackMemory CLI not found"
+        return 1
+    fi
+
+    if [ ! -d ".stackmemory" ]; then
+        log_warning "StackMemory not initialized"
+        return 1
+    fi
+
+    return 0
+}
+
+# Save branch context before switching
+save_branch_context() {
+    local branch="$1"
+    
+    if ! check_stackmemory; then
+        return 0
+    fi
+
+    log_info "Saving context for branch: $branch"
+
+    # Create branch-specific context backup
+    local branch_context_dir=".stackmemory/branches"
+    mkdir -p "$branch_context_dir"
+    
+    local context_file="$branch_context_dir/${branch//\//_}.json"
+    
+    # Save current state
+    local branch_context=$(cat << EOF
+{
+  "branch": "$branch",
+  "timestamp": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
+  "active_tasks": [],
+  "context_frames": [],
+  "last_commit": "$(git rev-parse HEAD 2>/dev/null || echo 'none')",
+  "working_directory_clean": $(git diff-index --quiet HEAD 2>/dev/null && echo 'true' || echo 'false')
+}
+EOF
+)
+
+    # Get active tasks and add to context
+    if stackmemory tasks list --status in-progress >/dev/null 2>&1; then
+        local active_tasks=$(stackmemory tasks list --status in-progress 2>/dev/null | grep -oE "tsk-[a-zA-Z0-9]+" || echo "")
+        
+        if [ -n "$active_tasks" ]; then
+            log_info "Found $(echo "$active_tasks" | wc -w | tr -d ' ') active tasks on branch $branch"
+            
+            # Save task details
+            for task_id in $active_tasks; do
+                local task_info=$(stackmemory task show "$task_id" 2>/dev/null || echo "")
+                if [ -n "$task_info" ]; then
+                    echo "$task_info" > "$branch_context_dir/${branch//\//_}_${task_id}.task"
+                fi
+            done
+        fi
+    fi
+
+    # Get current context frames
+    if stackmemory context show >/dev/null 2>&1; then
+        local context_frames=$(stackmemory context show 2>/dev/null || echo "")
+        if [ -n "$context_frames" ]; then
+            echo "$context_frames" > "$branch_context_dir/${branch//\//_}.context"
+        fi
+    fi
+
+    # Save the context summary
+    echo "$branch_context" > "$context_file"
+    
+    log_success "Context saved for branch: $branch"
+    return 0
+}
+
+# Load branch context after switching
+load_branch_context() {
+    local branch="$1"
+    
+    if ! check_stackmemory; then
+        return 0
+    fi
+
+    log_info "Loading context for branch: $branch"
+
+    local branch_context_dir=".stackmemory/branches"
+    local context_file="$branch_context_dir/${branch//\//_}.json"
+    
+    # Check if context exists for this branch
+    if [ ! -f "$context_file" ]; then
+        log_info "No saved context for branch: $branch (this is normal for new branches)"
+        
+        # Initialize new branch context
+        initialize_branch_context "$branch"
+        return 0
+    fi
+
+    # Load previous context
+    log_info "Restoring context from previous work on branch: $branch"
+
+    # Restore context frames if available
+    local context_frames_file="$branch_context_dir/${branch//\//_}.context"
+    if [ -f "$context_frames_file" ]; then
+        local saved_context=$(cat "$context_frames_file")
+        if [ -n "$saved_context" ]; then
+            log_info "Previous context frames available"
+            # Note: We don't automatically restore frames to avoid conflicts
+            # Users can manually check with: cat .stackmemory/branches/$(current_branch).context
+        fi
+    fi
+
+    # Show active tasks from this branch
+    local task_files=("$branch_context_dir/${branch//\//_}_tsk-"*.task)
+    if [ -f "${task_files[0]}" ]; then
+        local task_count=$(ls -1 "$branch_context_dir/${branch//\//_}_tsk-"*.task 2>/dev/null | wc -l | tr -d ' ')
+        log_info "Found $task_count saved tasks from previous work on this branch"
+        
+        # Optionally reactivate tasks
+        log_info "To reactivate tasks, run: stackmemory tasks list --all | grep 'your-task'"
+    fi
+
+    log_success "Context loaded for branch: $branch"
+    return 0
+}
+
+# Initialize context for new branch
+initialize_branch_context() {
+    local branch="$1"
+    
+    log_info "Initializing new branch context: $branch"
+
+    # Determine branch type and purpose from name
+    local branch_type="feature"
+    local suggested_tasks=""
+    
+    # Parse branch name for context
+    if echo "$branch" | grep -qE "^(feature|feat)/"; then
+        branch_type="feature"
+        suggested_tasks="Consider creating a feature task for this branch"
+    elif echo "$branch" | grep -qE "^(bugfix|fix)/"; then
+        branch_type="bugfix"
+        suggested_tasks="Consider creating a bug fix task for this branch"
+    elif echo "$branch" | grep -qE "^(hotfix)/"; then
+        branch_type="hotfix"
+        suggested_tasks="Consider creating a hotfix task with high priority"
+    elif echo "$branch" | grep -qE "^(refactor)/"; then
+        branch_type="refactor"
+        suggested_tasks="Consider creating a refactoring task for this branch"
+    elif echo "$branch" | grep -qE "^(test|testing)/"; then
+        branch_type="test"
+        suggested_tasks="Consider creating a testing task for this branch"
+    fi
+
+    # Create initial context frame for the branch
+    local frame_name="Branch: $branch"
+    if stackmemory start_frame --name "$frame_name" --type task >/dev/null 2>&1; then
+        log_success "Created initial frame for branch: $branch"
+        
+        # Add branch information as anchors
+        stackmemory add_anchor --type FACT --text "Working on branch: $branch" >/dev/null 2>&1
+        stackmemory add_anchor --type FACT --text "Branch type: $branch_type" >/dev/null 2>&1
+        
+        if [ -n "$suggested_tasks" ]; then
+            stackmemory add_anchor --type TODO --text "$suggested_tasks" >/dev/null 2>&1
+        fi
+        
+        log_info "Branch context initialized with type: $branch_type"
+    fi
+
+    return 0
+}
+
+# Handle branch switching
+handle_branch_switch() {
+    local previous_branch="$1"
+    local current_branch="$2"
+    
+    log_info "Branch switch detected: $previous_branch → $current_branch"
+
+    # Save context from previous branch
+    if [ -n "$previous_branch" ] && [ "$previous_branch" != "HEAD" ] && [ "$PRESERVE_CONTEXT" = "true" ]; then
+        save_branch_context "$previous_branch"
+    fi
+
+    # Load context for current branch
+    if [ "$AUTO_SWITCH_CONTEXT" = "true" ]; then
+        load_branch_context "$current_branch"
+    fi
+
+    # Show branch-specific guidance
+    provide_branch_guidance "$current_branch"
+
+    return 0
+}
+
+# Provide branch-specific guidance
+provide_branch_guidance() {
+    local branch="$1"
+    
+    # Skip guidance for main branches
+    if echo "$branch" | grep -qE "^(main|master|develop|dev)$"; then
+        log_info "On main branch: $branch"
+        return 0
+    fi
+
+    # Provide contextual guidance based on branch name
+    if echo "$branch" | grep -qE "^(feature|feat)/"; then
+        log_info "💡 Feature branch detected. Consider:"
+        log_info "   • Creating a task: stackmemory task add 'Implement feature X'"
+        log_info "   • Planning implementation: stackmemory start_frame --name 'Feature planning'"
+    elif echo "$branch" | grep -qE "^(bugfix|fix)/"; then
+        log_info "🐛 Bug fix branch detected. Consider:"
+        log_info "   • Creating a bug fix task with priority: stackmemory task add 'Fix bug X' --priority high"
+        log_info "   • Starting debugging frame: stackmemory start_frame --name 'Debug session' --type debug"
+    elif echo "$branch" | grep -qE "^(hotfix)/"; then
+        log_warning "🚨 Hotfix branch detected. Consider:"
+        log_warning "   • Creating urgent task: stackmemory task add 'Hotfix X' --priority critical"
+        log_warning "   • Tracking progress carefully for production release"
+    fi
+
+    return 0
+}
+
+# Filter tasks by branch prefix
+filter_tasks_by_branch() {
+    local branch="$1"
+    
+    if [ "$BRANCH_PREFIX_FILTERING" != "true" ]; then
+        return 0
+    fi
+
+    # Extract prefix from branch name (e.g., STA-123 from STA-123/feature-name)
+    local prefix=$(echo "$branch" | grep -oE "^[A-Z]+-[0-9]+" || echo "")
+    
+    if [ -n "$prefix" ]; then
+        log_info "Branch prefix detected: $prefix"
+        log_info "Showing related tasks..."
+        
+        # Show tasks that match the prefix
+        if stackmemory tasks list --search "$prefix" >/dev/null 2>&1; then
+            local matching_tasks=$(stackmemory tasks list --search "$prefix" 2>/dev/null || echo "")
+            if [ -n "$matching_tasks" ] && [ "$matching_tasks" != "No tasks found" ]; then
+                echo ""
+                echo "$matching_tasks"
+                echo ""
+            fi
+        fi
+    fi
+
+    return 0
+}
+
+# Main execution function
+main() {
+    local action="${1:-switch}"
+    local previous_branch="${2:-}"
+    local current_branch="${3:-}"
+    
+    # Auto-detect branch information if not provided
+    if [ -z "$current_branch" ]; then
+        current_branch=$(get_current_branch)
+    fi
+    
+    if [ -z "$previous_branch" ] && [ "$action" = "switch" ]; then
+        previous_branch=$(get_previous_branch)
+    fi
+
+    case "$action" in
+        "switch")
+            if [ "$BRANCH_ISOLATION_ENABLED" = "true" ]; then
+                handle_branch_switch "$previous_branch" "$current_branch"
+                filter_tasks_by_branch "$current_branch"
+            fi
+            ;;
+        "save")
+            save_branch_context "$current_branch"
+            ;;
+        "load")
+            load_branch_context "$current_branch"
+            ;;
+        "init")
+            initialize_branch_context "$current_branch"
+            ;;
+        *)
+            log_error "Usage: $0 {switch|save|load|init} [previous_branch] [current_branch]"
+            exit 1
+            ;;
+    esac
+
+    return 0
+}
+
+# Run main function if script is executed directly
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+    main "$@"
+fi

package/scripts/git-hooks/post-checkout-stackmemory.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# StackMemory Post-Checkout Hook
+# Handles branch context switching and task isolation
+
+set -e
+
+# Hook parameters from git
+prev_head="$1"
+new_head="$2"
+is_branch_checkout="$3"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+log_info() {
+    echo -e "${BLUE}ℹ️  $1${NC}"
+}
+
+log_success() {
+    echo -e "${GREEN}✅ $1${NC}"
+}
+
+log_warning() {
+    echo -e "${YELLOW}⚠️  $1${NC}"
+}
+
+# Only process branch checkouts
+if [ "$is_branch_checkout" != "1" ]; then
+    exit 0
+fi
+
+# Check if StackMemory is available
+if ! command -v stackmemory >/dev/null 2>&1 || [ ! -d ".stackmemory" ]; then
+    exit 0
+fi
+
+# Get script directory
+SCRIPT_DIR="$(dirname "$0")"
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+
+# Source the branch context manager
+if [ -f "$REPO_ROOT/scripts/git-hooks/branch-context-manager.sh" ]; then
+    source "$REPO_ROOT/scripts/git-hooks/branch-context-manager.sh"
+else
+    log_warning "Branch context manager not found, skipping branch isolation"
+    exit 0
+fi
+
+# Get branch names
+current_branch=$(git branch --show-current 2>/dev/null || echo "HEAD")
+previous_branch=$(git name-rev --name-only "$prev_head" 2>/dev/null | sed 's/^[^/]*\///' || echo "")
+
+log_info "🔀 Branch checkout detected: switching to $current_branch"
+
+# Handle the branch switch
+main "switch" "$previous_branch" "$current_branch"
+
+log_success "Branch context switch completed"
+exit 0