@humanu/orchestra 0.5.36 → 0.5.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanu/orchestra",
-  "version": "0.5.36",
+  "version": "0.5.37",
   "description": "AI-powered Git worktree and tmux session manager with modern TUI",
   "keywords": [
     "git",

package/resources/scripts/gw.sh

@@ -136,11 +136,13 @@ usage() {
   echo "  ch, checkout <branch>         Switch to the worktree of <branch>"
   echo "  copy-env <worktreename>       Copy env files from current worktree to target"
   echo "  status [git status args]      Show current worktree + git status"
+  echo "  update, --update              Check for available updates"
   echo ""
   echo "Examples:"
   echo "  $(basename "$0")             # interactive picker (tmux session management)"
   echo "  $(basename "$0") ls          # list worktrees only"
   echo "  $(basename "$0") ch -b feat/x # create and switch to worktree"
+  echo "  $(basename "$0") update      # check for available updates"
   echo ""
   echo "Note: tmux session management is only available via the interactive menu (no args)."
 }
@@ -190,6 +192,7 @@ case "$COMMAND" in
   ch|checkout)         cmd_checkout_worktree "$@" ;;
   status)              cmd_status "$@" ;;
   copy-env)            cmd_copy_env "$@" ;;
+  update|--update)     "$SCRIPT_DIR/shell/gwr/check-updates.sh" ;;
   help|-h|--help)      usage ;;
   *)                   err "Unknown command '$COMMAND'"; usage ;;
  esac

package/resources/scripts/gwr.sh

@@ -46,6 +46,12 @@ if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
     exit 0
 fi
 
+# Handle update check flag
+if [[ "${1:-}" == "--check-updates" || "${1:-}" == "--update" ]]; then
+    "$SCRIPT_DIR/shell/gwr/check-updates.sh"
+    exit $?
+fi
+
 # Check prerequisites
 gwr_check_git_repo
 gwr_check_bridge_script
@@ -74,6 +80,9 @@ BRIDGE_PATH="$SCRIPT_DIR/gw-bridge.sh"
 
 gwr_set_terminal_title
 
+# Check for updates silently (once per day)
+gwr_check_updates_silent
+
 exec "$BINARY_PATH" --bridge-path "$BRIDGE_PATH" "$@"
 
 # Handle help flag early
@@ -82,6 +91,12 @@ if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
     exit 0
 fi
 
+# Handle update check flag
+if [[ "${1:-}" == "--check-updates" || "${1:-}" == "--update" ]]; then
+    "$SCRIPT_DIR/shell/gwr/check-updates.sh"
+    exit $?
+fi
+
 # Check prerequisites
 check_git_repo
 check_bridge_script

package/resources/scripts/shell/AGENTS.md

@@ -0,0 +1,236 @@
+# Shell Directory - AI Context Documentation
+
+This document provides comprehensive context for AI agents and LLMs working with the Orchestrator shell system. It describes the purpose, structure, and usage of all files in the `shell/` directory and its subdirectories.
+
+## Directory Structure Overview
+
+```
+shell/
+├── gwr_load.sh              # Main loader for gwr (Rust TUI) components
+├── gwr_colors.sh            # Color definitions and terminal styling
+├── gwr_logging.sh           # Logging utilities and output formatting
+├── gwr_git.sh               # Git repository validation functions
+├── gwr_bridge.sh            # Bridge script validation and setup
+├── gwr_binary.sh            # Binary discovery and validation
+├── gwr_terminal.sh          # Terminal title and environment setup
+├── gwr_usage.sh             # Usage/help text for gwr command
+├── gw_load.sh               # Main loader for gw (CLI) components
+├── gw_colors.sh             # Color definitions for gw CLI
+├── gw_logging.sh            # Logging for gw CLI
+├── gw_git.sh                # Git operations for gw CLI
+├── gw_worktree.sh           # Worktree management for gw CLI
+├── gw_usage.sh              # Usage text for gw command
+├── copy_env.sh              # Environment variable copying system
+├── commands.sh              # Shared command utilities
+├── build/                   # Build system components
+│   ├── build_bridge.sh      # Bridge building logic
+│   ├── build_dependencies.sh # Dependency checking
+│   ├── build_install.sh     # Installation procedures
+│   ├── build_load.sh        # Build system loader
+│   ├── build_logging.sh     # Build-specific logging
+│   ├── build_rust.sh        # Rust compilation logic
+│   └── build_usage.sh       # Build command usage
+├── env/                     # Environment management
+│   ├── copy_env_command.sh  # Command processing for env copying
+│   ├── copy_env_constants.sh # Constants and paths
+│   ├── copy_env_core.sh     # Core environment copying logic
+│   ├── copy_env_debug_parse.sh # Debug parsing for env copying
+│   ├── copy_env_load.sh     # Environment loader
+│   ├── copy_env_locations.sh # Path and location management
+│   ├── copy_env_logging.sh  # Environment copying logging
+│   └── copy_env_state.sh    # State management for env copying
+├── git/                     # Git-specific utilities
+│   └── gwr_worktree_title.sh # Worktree title generation
+└── gwr/                     # gwr-specific components
+    └── check-updates.sh     # Update checking functionality
+```
+
+## Core System Files
+
+### gwr_load.sh
+**Purpose**: Main loader for the gwr (Rust TUI) system
+**Usage**: Sourced by gwr.sh to load all necessary components
+**Key Functions**: 
+- Loads all gwr-specific modules in correct order
+- Provides `gwr_load_core()` function
+**Dependencies**: All gwr_*.sh files in shell/
+
+### gwr_colors.sh
+**Purpose**: Color definitions and terminal styling for gwr
+**Usage**: Provides consistent color scheme across gwr components
+**Key Variables**:
+- `BLUE`, `GREEN`, `YELLOW`, `RED`, `NC` - ANSI color codes
+- Used for status messages, errors, and UI feedback
+
+### gwr_logging.sh
+**Purpose**: Logging and output formatting utilities
+**Usage**: Standardized logging functions for gwr operations
+**Key Functions**:
+- `gwr_info()`, `gwr_success()`, `gwr_warn()`, `gwr_error()` - Colored logging functions
+- Provides consistent output formatting across gwr system
+
+### gwr_git.sh
+**Purpose**: Git repository validation and setup
+**Usage**: Ensures gwr runs in valid git repositories
+**Key Functions**:
+- `gwr_check_git_repo()` - Validates git repository presence
+- Provides error messages and guidance for git setup
+
+### gwr_bridge.sh
+**Purpose**: Bridge script validation and setup
+**Usage**: Ensures gw-bridge.sh is available and executable
+**Key Functions**:
+- `gwr_check_bridge_script()` - Validates bridge script presence
+- Critical for Rust TUI communication with bash APIs
+
+### gwr_binary.sh
+**Purpose**: Binary discovery and validation for Rust TUI
+**Usage**: Finds and validates gw-tui binary location
+**Key Functions**:
+- `gwr_find_binary()` - Searches for gw-tui binary in multiple locations
+- Supports development, release, and installed binary locations
+- Handles GW_TUI_BIN environment variable override
+
+### gwr_terminal.sh
+**Purpose**: Terminal environment setup
+**Usage**: Configures terminal for optimal TUI experience
+**Key Functions**:
+- `gwr_set_terminal_title()` - Sets terminal window title
+- Provides terminal compatibility and environment setup
+
+### gwr_usage.sh
+**Purpose**: Help and usage information for gwr command
+**Usage**: Displays comprehensive help text
+**Key Functions**:
+- `gwr_show_usage()` - Shows command-line options and navigation help
+- Includes keyboard shortcuts, examples, and requirements
+
+## CLI System Files (gw_*)
+
+### gw_load.sh
+**Purpose**: Main loader for the gw (CLI) system
+**Usage**: Sourced by gw.sh to load CLI-specific components
+**Key Functions**: 
+- Loads all gw-specific modules in correct order
+- Provides `gw_load_core()` function
+**Dependencies**: All gw_*.sh files in shell/
+
+### gw_colors.sh, gw_logging.sh, gw_git.sh, gw_worktree.sh, gw_usage.sh
+**Purpose**: CLI equivalents of gwr modules
+**Usage**: Provide CLI-specific implementations of core functionality
+**Key Differences**: Optimized for command-line usage rather than TUI interaction
+
+## Shared System Files
+
+### copy_env.sh
+**Purpose**: Environment variable copying system
+**Usage**: Copies environment between shell contexts
+**Key Functions**:
+- `copy_env()` - Main function for environment copying
+- Critical for worktree directory changes and session management
+- Used by both gwr and gw systems
+
+### commands.sh
+**Purpose**: Shared command utilities
+**Usage**: Common command-line operations used across systems
+**Key Functions**:
+- `have_command()` - Command availability checking
+- Shared utility functions for both gwr and gw systems
+
+## Build System (build/)
+
+### build_load.sh
+**Purpose**: Loader for build system components
+**Usage**: Loads all build-related modules
+**Key Functions**: `build_load_core()` - Loads build system modules
+
+### build_rust.sh
+**Purpose**: Rust compilation and binary management
+**Usage**: Handles Rust TUI compilation and installation
+**Key Functions**:
+- Rust project compilation
+- Binary installation and management
+- Cross-platform binary handling
+
+### build_bridge.sh, build_dependencies.sh, build_install.sh, build_logging.sh, build_usage.sh
+**Purpose**: Specialized build system components
+**Usage**: Handle specific aspects of the build process
+**Key Functions**: Each focuses on a specific build operation
+
+## Environment System (env/)
+
+### copy_env_core.sh
+**Purpose**: Core environment copying logic
+**Usage**: Main implementation of environment variable copying
+**Key Functions**: `copy_env()` - Core function for environment management
+
+### copy_env_command.sh, copy_env_constants.sh, copy_env_debug_parse.sh, copy_env_load.sh, copy_env_locations.sh, copy_env_logging.sh, copy_env_state.sh
+**Purpose**: Specialized environment copying components
+**Usage**: Handle specific aspects of environment management
+**Key Functions**: Each module handles a specific aspect of the complex environment copying system
+
+## Git Utilities (git/)
+
+### gwr_worktree_title.sh
+**Purpose**: Worktree title generation for tmux sessions
+**Usage**: Creates descriptive titles for worktree-based tmux sessions
+**Key Functions**: `gwr_worktree_title()` - Generates formatted worktree titles
+
+## Update System (gwr/)
+
+### check-updates.sh
+**Purpose**: Update checking functionality
+**Usage**: Checks for newer versions from npm and homebrew
+**Key Functions**:
+- `detect_installation_method()` - Determines how Orchestra was installed
+- `get_npm_latest_version()`, `get_brew_latest_version()` - Fetches latest versions
+- `check_updates()` - Main update checking logic
+- Provides update instructions based on installation method
+
+## Integration Points
+
+### gwr.sh Integration
+- Sources `gwr_load.sh` to load all gwr components
+- Uses `--check-updates` flag to trigger update checking
+- Passes bridge path to Rust TUI binary
+
+### gw.sh Integration
+- Sources `gw_load.sh` to load all gw components
+- Uses shared `copy_env.sh` for environment management
+- Provides CLI interface to same underlying functionality
+
+### Bridge System Integration
+- `gwr_bridge.sh` validates bridge script availability
+- Bridge script enables Rust TUI to communicate with bash APIs
+- Critical for the hybrid Rust/bash architecture
+
+## Key Architectural Patterns
+
+1. **Modular Loading**: Each system (gwr/gw) has its own loader that sources components in dependency order
+2. **Color Consistency**: Separate color files ensure consistent theming across components
+3. **Logging Standardization**: Standardized logging functions provide consistent output
+4. **Environment Isolation**: Complex environment copying system handles shell context changes
+5. **Binary Discovery**: Sophisticated binary finding supports development, build, and installed scenarios
+6. **Update Integration**: Update checking integrated into main launcher with installation method detection
+
+## Usage Examples for AI Agents
+
+### Adding New gwr Functionality
+1. Create new function in appropriate module (e.g., `gwr_new_feature.sh`)
+2. Add to `gwr_load.sh` loading sequence
+3. Update `gwr_usage.sh` if adding user-facing features
+4. Follow existing patterns for colors, logging, and error handling
+
+### Modifying Update Checking
+1. Edit `shell/gwr/check-updates.sh`
+2. Update version constants if needed
+3. Test with different installation methods (npm, brew, local)
+4. Ensure graceful handling of missing package managers
+
+### Adding Build System Features
+1. Create new module in `shell/build/`
+2. Add to `build_load.sh` if needed
+3. Follow existing build system patterns
+4. Update `build_usage.sh` for new build options
+
+This documentation provides the foundation for AI agents to understand and work effectively with the Orchestrator shell system.

package/resources/scripts/shell/gwr/check-updates.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+
+###############################################################################
+# check-updates.sh - Check for Orchestra updates from npm and brew
+#
+# Determines installation method and checks for newer versions
+###############################################################################
+
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+info() { printf "${BLUE}[UPDATE]${NC} %s\n" "$*"; }
+success() { printf "${GREEN}[UPDATE]${NC} %s\n" "$*"; }
+warn() { printf "${YELLOW}[UPDATE]${NC} %s\n" "$*"; }
+error() { printf "${RED}[UPDATE]${NC} %s\n" "$*"; }
+
+# Current version (should match package.json and homebrew formula)
+CURRENT_VERSION="0.5.35"
+NPM_PACKAGE="@humanu/orchestra"
+BREW_FORMULA="orchestra"
+
+# Function to get latest npm version
+get_npm_latest_version() {
+    if command -v npm >/dev/null 2>&1; then
+        npm view "$NPM_PACKAGE" version 2>/dev/null || echo "unknown"
+    else
+        echo "npm_not_found"
+    fi
+}
+
+# Function to get latest homebrew version
+get_brew_latest_version() {
+    if command -v brew >/dev/null 2>&1; then
+        brew info --json "$BREW_FORMULA" 2>/dev/null | \
+            python3 -c "import sys, json; data = json.load(sys.stdin); print(data[0]['versions']['stable'])" 2>/dev/null || \
+        echo "unknown"
+    else
+        echo "brew_not_found"
+    fi
+}
+
+# Function to detect installation method
+detect_installation_method() {
+    local method="unknown"
+    
+    # Check if installed via npm
+    if command -v npm >/dev/null 2>&1; then
+        if npm list -g "$NPM_PACKAGE" >/dev/null 2>&1; then
+            method="npm"
+        fi
+    fi
+    
+    # Check if installed via homebrew (override npm if both)
+    if command -v brew >/dev/null 2>&1; then
+        if brew list "$BREW_FORMULA" >/dev/null 2>&1; then
+            method="brew"
+        fi
+    fi
+    
+    # Check if running from local development
+    if [[ -f "$(dirname "${BASH_SOURCE[0]}")/../../../gw-tui/Cargo.toml" ]]; then
+        method="local"
+    fi
+    
+    echo "$method"
+}
+
+# Function to compare versions (simple string comparison)
+version_compare() {
+    local current="$1" latest="$2"
+    
+    if [[ "$current" == "$latest" ]]; then
+        echo "equal"
+    else
+        # Simple version comparison - this works for most semantic versions
+        if [[ "$current" < "$latest" ]]; then
+            echo "older"
+        else
+            echo "newer"
+        fi
+    fi
+}
+
+# Main update check function
+check_updates() {
+    info "Checking for Orchestra updates..."
+    echo
+    
+    # Detect installation method
+    local install_method
+    install_method=$(detect_installation_method)
+    info "Detected installation method: $install_method"
+    
+    # Get current and latest versions based on installation method
+    local current_version latest_version comparison
+    
+    case "$install_method" in
+        "npm")
+            current_version=$(npm list -g "$NPM_PACKAGE" 2>/dev/null | grep "$NPM_PACKAGE@" | sed 's/.*@//' | head -1)
+            latest_version=$(get_npm_latest_version)
+            ;;
+        "brew")
+            current_version=$(brew info --json "$BREW_FORMULA" 2>/dev/null | \
+                python3 -c "import sys, json; data = json.load(sys.stdin); print(data[0]['installed'][0]['version'])" 2>/dev/null || \
+                echo "$CURRENT_VERSION")
+            latest_version=$(get_brew_latest_version)
+            ;;
+        "local")
+            info "Running from local development source"
+            info "Current version: $CURRENT_VERSION (development)"
+            info "To update, pull latest changes from git repository"
+            return 0
+            ;;
+        *)
+            warn "Could not detect installation method"
+            current_version="$CURRENT_VERSION"
+            latest_version=$(get_npm_latest_version)
+            ;;
+    esac
+    
+    echo
+    info "Current version: $current_version"
+    info "Latest version: $latest_version"
+    echo
+    
+    # Compare versions
+    comparison=$(version_compare "$current_version" "$latest_version")
+    
+    case "$comparison" in
+        "equal")
+            success "✅ You are running the latest version!"
+            ;;
+        "older")
+            warn "⚠️  A newer version is available!"
+            echo
+            info "Update instructions:"
+            case "$install_method" in
+                "npm")
+                    echo "  npm install -g $NPM_PACKAGE"
+                    ;;
+                "brew")
+                    echo "  brew upgrade $BREW_FORMULA"
+                    ;;
+                *)
+                    echo "  npm install -g $NPM_PACKAGE"
+                    echo "  or"
+                    echo "  brew install $BREW_FORMULA"
+                    ;;
+            esac
+            echo
+            info "Release notes: https://github.com/humanunsupervised/orchestra/releases"
+            return 1
+            ;;
+        "newer")
+            success "✅ You are running a newer version than latest release!"
+            info "This might be a development or pre-release version."
+            ;;
+        *)
+            error "Could not determine version comparison"
+            return 1
+            ;;
+    esac
+    
+    return 0
+}
+
+# Run the update check
+check_updates "$@"

package/resources/scripts/shell/gwr_binary.sh

@@ -23,3 +23,33 @@ gwr_find_binary() {
 
     return 1
 }
+
+gwr_should_check_updates() {
+    # Check if we should run update check (once per day)
+    local last_check_file="${HOME}/.cache/orchestra/last_update_check"
+    local current_time=$(date +%s)
+    local last_check=0
+    
+    if [[ -f "$last_check_file" ]]; then
+        last_check=$(cat "$last_check_file" 2>/dev/null || echo 0)
+    fi
+    
+    # Check if more than 24 hours have passed (86400 seconds)
+    local time_diff=$((current_time - last_check))
+    if [[ $time_diff -gt 86400 ]]; then
+        # Create cache directory if it doesn't exist
+        mkdir -p "$(dirname "$last_check_file")"
+        echo "$current_time" > "$last_check_file"
+        return 0
+    fi
+    
+    return 1
+}
+
+gwr_check_updates_silent() {
+    # Silent update check that doesn't interfere with normal operation
+    if gwr_should_check_updates; then
+        # Run update check in background, only show if update available
+        "$SCRIPT_DIR/shell/gwr/check-updates.sh" 2>/dev/null | grep -E "(⚠️|newer version|Update instructions)" || true
+    fi
+}

package/resources/scripts/shell/gwr_usage.sh

@@ -11,6 +11,8 @@ A terminal user interface for managing git worktrees and tmux sessions.
 Options:
   -d, --debug     Enable debug mode
   -h, --help      Show this help
+  --check-updates Check for available updates
+  --update        Check for available updates (alias for --check-updates)
 
 Features:
   • Interactive worktree and session management
@@ -44,6 +46,7 @@ Examples:
   gwr             # Launch interactive TUI
   gwr --debug     # Launch with debug information
   gwr --help      # Show this help
+  gwr --update    # Check for available updates
 
 EOF
 }