argos

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [2.0.0] - 2025-01-15

### 🎉 Major Release

Version 2.0.0 is a comprehensive release that provides a complete solution for command execution, parallel task orchestration, and system integration in Elixir. This version introduces a robust CLI tool, advanced parallel execution system, and extensive API for programmatic use.

### ✨ Features

#### 🖥️ Command Execution Module

**Core Execution Functions:**
- `Argos.Command.exec/2` - Execute commands with structured results (`CommandResult` struct)
- `Argos.Command.exec_raw/2` - Execute commands without additional logging, returns `{output, exit_code}`
- `Argos.Command.exec_silent/2` - Execute silently, returns only exit code
- `Argos.Command.exec_interactive/2` - Execute commands interactively (for commands requiring input)
- `Argos.Command.exec_sudo/2` - Execute commands with sudo privileges

**Command Result Structure:**
- `CommandResult` struct with fields: `command`, `args`, `output`, `exit_code`, `success?`, `error`, `duration`
- Comprehensive error handling with detailed error messages
- Duration tracking in milliseconds
- Success/failure boolean flag

**Execution Options:**
- `circuit_breaker: true` - Enable circuit breaker pattern for fault tolerance
- `halt: false` - Don't halt on error (default: true)
- `env: [{"KEY", "value"}]` - Custom environment variables
- Input validation before execution
- Support for both string and list commands

#### 🔄 Circuit Breaker Pattern

**Built-in Fault Tolerance:**
- `Argos.Command.CircuitBreaker` - Circuit breaker GenServer implementation
- Three states: `:closed` (normal), `:open` (rejecting), `:half_open` (testing)
- Configurable threshold and timeout
- Automatic state transitions
- Success/failure tracking
- Manual reset capability

**Configuration:**
- Configurable via `config :argos, :circuit_breaker`
- Options: `threshold`, `timeout`, `enabled`
- Per-command circuit breaker support

#### 🔧 ASDF Integration

**Version Management:**
- `Argos.Command.asdf_exec/3` - Execute commands using ASDF with project-specific versions
- Automatic `.tool-versions` file detection
- Project path detection from commands (supports `cd` and aliases)
- PATH configuration with ASDF shims
- Fallback to normal execution if `.tool-versions` doesn't exist
- Support for multiple tool versions (Elixir, Erlang, etc.)

**Features:**
- Reads and validates `.tool-versions` files
- Uses `asdf exec` for version-specific execution
- Preserves environment variables
- Automatic project path extraction from commands

#### ⚡ Parallel Task Orchestration

**System Architecture:**
- `Argos.Parallel` - Complete parallel execution system
- Leader-Worker-Monitor architecture
- Supervisor-based process management
- Event-driven communication

**Core Functions:**
- `Argos.Parallel.start_system/1` - Initialize parallel execution system
- `Argos.Parallel.stop_system/0` - Stop system and clean up resources
- `Argos.Parallel.create_worker_spec/3` - Create worker specifications
- `Argos.Parallel.start_workers/2` - Start multiple workers concurrently
- `Argos.Parallel.stop_worker/2` - Stop specific worker by ID

**Event Subscription:**
- `Argos.Parallel.subscribe/1` - Subscribe to individual worker events (Leader)
- `Argos.Parallel.subscribe_leader/1` - Subscribe to Leader events
- `Argos.Parallel.subscribe_monitor/1` - Subscribe to aggregated monitor state
- `Argos.Parallel.unsubscribe/1` - Unsubscribe from events
- `Argos.Parallel.unsubscribe_leader/1` - Unsubscribe from Leader
- `Argos.Parallel.unsubscribe_monitor/1` - Unsubscribe from Monitor

**State Management:**
- `Argos.Parallel.get_state/1` - Get current system state
- `Argos.Parallel.get_leader_state/1` - Get Leader state
- `Argos.Parallel.get_monitor_state/1` - Get aggregated monitor state
- `Argos.Parallel.get_worker_state/2` - Get specific worker state
- `Argos.Parallel.get_stats/1` - Get statistics about all workers

**Worker Features:**
- Sequential task execution within workers
- Parallel execution across workers
- Progress tracking per worker
- Error handling and reporting
- Optional individual log files per worker
- Configurable timeouts

**Event Types:**
- `:result` - Task completion with result data
- `:progress` - Progress update with percentage
- `:finished` - Worker completion
- `:error` - Error occurrence with details

#### 📝 Logging System

**Structured Logging:**
- `Argos.log/3` - Structured logging with metadata
- Integration with Aurora for beautiful terminal output
- Custom logger backend support via `Argos.Logger.Behaviour`
- Default logger implementation
- Configurable logger per application

**Parallel Worker Logging:**
- `Argos.Parallel.Logger` - Individual log files per worker
- JSON Lines format (`.jsonl`) for structured logs
- Automatic log file management
- Log cleanup on system stop
- Real-time log access during execution
- Functions: `get_log_path/1`, `read_log/1`, `read_log_tail/2`, `list_active_logs/0`

#### 🔍 Validation Module

**Input Validation:**
- `Argos.Validation.validate_command/1` - Validate commands before execution
- `Argos.Validation.validate_process_name/1` - Validate process names
- `Argos.Validation.validate_path/1` - Validate file/directory paths
- `Argos.Validation.validate_worker_spec/1` - Validate worker specifications
- `Argos.Validation.escape_process_name/1` - Escape process names for safe shell usage

**Security Features:**
- Injection prevention
- Input sanitization
- Length and format validation
- Pattern matching validation

#### 🛑 Process Management

**Process Control:**
- `Argos.Command.kill_process/1` - Kill process by name
- `Argos.Command.kill_processes_by_name/1` - Kill multiple processes
- Process name validation
- Safe process termination
- Error handling for non-existent processes

#### 🖥️ CLI Tool

**Command-Line Interface:**
- Standalone executable (`argos`) via `mix escript.build`
- Parallel command execution from terminal
- ANSI code preservation
- Real-time output display

**CLI Options:**
- `-c, --command="COMMAND"` - Execute command (can be specified multiple times)
- `--load-config` - Explicitly load shell configuration file
- `--no-config` - Don't load shell configuration file
- `--no-login` - (Deprecated) Equivalent to `--no-config`
- `--asdf-local` - Use ASDF versions from project's `.tool-versions` file
- `-h, --help` - Show help (contextual help for specific commands)
- `-e, --examples` - Show usage examples
- `-v, --version` - Show version

**CLI Features:**
- Parallel execution using Elixir Tasks
- Real-time output with ANSI preservation
- Shell configuration loading (`.zshrc`, `.bashrc`, etc.)
- Automatic configuration file detection
- Exit code: 0 if all commands succeed, 1 if any fails
- Contextual help system (`argos <command> --help`)

**Help System:**
- Main help with all options and examples
- Contextual help for specific commands
- Usage examples section
- Professional formatting with Aurora

#### 🏗️ Architecture

**Modular Design:**
- `Argos.Command` - Command execution module
- `Argos.Parallel` - Parallel orchestration system
- `Argos.Validation` - Input validation
- `Argos.Logger` - Logging system
- `Argos.CLI` - Command-line interface
- `Argos.CLI.Parser` - Argument parsing
- `Argos.CLI.Executor` - Command execution
- `Argos.CLI.Formatter` - Output formatting

**Parallel System Components:**
- `Argos.Parallel.Leader` - Coordinates worker lifecycle
- `Argos.Parallel.Monitor` - Aggregates state from all workers
- `Argos.Parallel.Supervisor` - Supervises all system processes
- `Argos.Parallel.Worker` - Executes tasks sequentially
- `Argos.Parallel.Logger` - Individual log files per worker
- `Argos.Parallel.Example` - Complete usage example

#### ⚙️ Configuration

**Application Configuration:**
- Circuit breaker settings
- Logger backend configuration
- Shell configuration (default shell, timeout)
- Compile-time and runtime configuration support

**Environment Support:**
- Development, test, and production environments
- Configurable timeouts
- Custom logger implementations
- Shell-specific settings

#### 📚 Documentation

**Comprehensive Documentation:**
- Complete `@moduledoc` for all modules
- `@doc` for all public functions
- `@spec` type specifications
- Usage examples in documentation
- Professional README in English
- API reference with examples

#### 🧪 Testing

**Test Coverage:**
- Comprehensive test suite
- Unit tests for all modules
- Integration tests for CLI
- Parallel execution tests
- Error handling tests
- Edge case coverage

#### 🔧 Development Tools

**Code Quality:**
- Credo static analysis
- Dialyzer type checking
- ExUnit test framework
- ExCoveralls coverage tracking
- Mix aliases for common tasks

**Mix Aliases:**
- `mix quality` - Run all quality checks
- `mix test` - Run tests
- `mix credo` - Run Credo
- `mix dialyzer` - Run Dialyzer
- `mix format` - Format code
- `mix compile.strict` - Strict compilation

### 🎯 Use Cases

**Command Execution:**
- System administration tasks
- Build and deployment scripts
- CI/CD pipeline integration
- Automated testing
- Process management

**Parallel Orchestration:**
- Concurrent data processing
- Parallel test execution
- Batch job processing
- Task queue management
- Distributed computing

**CLI Tool:**
- Development workflow automation
- Parallel command execution
- Shell script replacement
- Build system integration
- DevOps tooling

### 📦 Dependencies

- **Aurora** (>= 2.0.0) - Terminal formatting and colors
- **Elixir** (>= 1.18.2-otp-27) - Core language requirement

### 🔄 Migration Notes

This is the first major release (2.0.0). If upgrading from a previous version:

1. Update dependencies in `mix.exs`
2. Review API changes in documentation
3. Update any custom logger implementations to use `Argos.Logger.Behaviour`
4. Check configuration format changes

### 📄 License

Apache 2.0 - See [LICENSE](LICENSE) for details.

---

**Made with ⚡ for reliable command execution and parallel task orchestration**