initial commit

README.md

@@ -0,0 +1,195 @@
+# Hero Supervisor
+
+A Rust-based actor management system for the Hero ecosystem that provides unified process management, job queuing, and optional OpenRPC server integration.
+
+## Architecture Overview
+
+The Hero Supervisor uses a clean, feature-gated architecture that separates library functionality from CLI/server features to avoid dependency cycles and maintain modularity.
+
+```
+hero-supervisor/
+├── src/                    # Core library (no CLI dependencies)
+│   ├── lib.rs             # Main library exports and documentation
+│   ├── supervisor.rs      # Core supervisor logic and actor management
+│   ├── runner.rs          # Runner implementation for actor process management
+│   ├── job.rs            # Job data structures, builder pattern, and Redis key management
+│   └── openrpc.rs        # OpenRPC server (feature-gated)
+├── cmd/                   # CLI binaries
+
+## Features
+
+The crate uses Rust's feature system to provide conditional compilation:
+
+- **`default`**: Includes all functionality - supervisor, OpenRPC server, and CLI binary
+- **`cli`**: Enables the supervisor binary (included in default)
+
+## Architecture
+
+The Hero Supervisor uses a clean, simplified architecture with centralized resource management:
+
+### Core Components
+
+#### `SupervisorBuilder` → `Supervisor` → `SupervisorApp`
+- **`SupervisorBuilder`**: Configures Redis URL, namespace, secrets, runners, and process manager
+- **`Supervisor`**: Core engine that owns Redis client and process manager, manages runners centrally
+- **`SupervisorApp`**: Main application that wraps supervisor and provides `start()` method for complete lifecycle management
+
+### Key Design Decisions
+
+- **Centralized Resources**: Supervisor exclusively owns Redis client and process manager (no per-runner instances)
+- **Builder Pattern**: Flexible configuration through `SupervisorBuilder` with method chaining
+- **Direct OpenRPC Integration**: RPC trait implemented directly on `Arc<Mutex<Supervisor>>` (no wrapper layers)
+- **Simplified App**: `SupervisorApp::start()` handles everything - runners, OpenRPC server, graceful shutdown
+
+## File Documentation
+
+### Core Library Files
+
+#### `src/lib.rs`
+Main library entry point that exports `Supervisor`, `SupervisorBuilder`, `SupervisorApp`, and related types.
+
+#### `src/supervisor.rs`
+Core supervisor implementation with builder pattern. Manages runners, owns shared Redis client and process manager. Provides job queuing, runner lifecycle management, and status monitoring.
+
+#### `src/app.rs`
+Main application wrapper that provides `start()` method for complete lifecycle management. Handles OpenRPC server startup, graceful shutdown, and keeps the application running.
+
+#### `src/runner.rs`
+Simplified runner configuration and management. Contains `Runner` struct with configuration data only - no resource ownership. Integrates with supervisor's shared resources.
+
+#### `src/job.rs`
+Job data structures, builder pattern, and Redis key management. Defines `Job` struct with metadata, script content, and status tracking.
+
+#### `src/openrpc.rs`
+OpenRPC server implementation that exposes all supervisor functionality over JSON-RPC. Implements RPC trait directly on the supervisor for clean integration.
+
+### Binary Files
+
+#### `cmd/supervisor.rs`
+Main supervisor binary that creates a supervisor using the builder pattern and starts the complete application with `app.start()`. The OpenRPC server is always enabled and starts automatically.
+
+## Usage
+
+### Running the Supervisor Binary
+
+```bash
+# Run with default (error) logging
+cargo run --bin supervisor
+
+# Run with info logging
+RUST_LOG=info cargo run --bin supervisor
+
+# Run with debug logging  
+RUST_LOG=debug cargo run --bin supervisor
+
+# Run with trace logging (very verbose)
+RUST_LOG=trace cargo run --bin supervisor
+
+# Run with specific module logging
+RUST_LOG=hero_supervisor=debug cargo run --bin supervisor
+```
+
+### Library Usage
+
+```rust
+use hero_supervisor::{SupervisorBuilder, SupervisorApp};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Build supervisor with configuration
+    let supervisor = SupervisorBuilder::new()
+        .redis_url("redis://localhost:6379")
+        .namespace("hero")
+        .build()
+        .await?;
+    
+    // Create and start the complete application
+    let mut app = SupervisorApp::new(supervisor);
+    app.start().await?;
+    
+    Ok(())
+}
+```
+
+### As a Dependency
+```toml
+[dependencies]
+hero-supervisor = "0.1.0"
+```
+
+## OpenRPC Server
+
+The supervisor automatically starts an OpenRPC server on `127.0.0.1:3030` that exposes all supervisor functionality via JSON-RPC.
+
+### Available Methods
+
+- `add_runner` - Add a new actor/runner
+- `remove_runner` - Remove an actor/runner
+- `list_runners` - List all runner IDs
+- `start_runner` - Start a specific runner
+- `stop_runner` - Stop a specific runner
+- `get_runner_status` - Get status of a specific runner
+- `get_runner_logs` - Get logs for a specific runner
+- `queue_job_to_runner` - Queue a job to a specific runner
+- `get_all_runner_status` - Get status of all runners
+- `start_all` - Start all runners
+- `stop_all` - Stop all runners
+- `get_all_status` - Get status summary for all runners
+
+### Example JSON-RPC Call
+
+```bash
+curl -X POST -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"list_runners","id":1}' \
+  http://127.0.0.1:3030
+```
+
+## Development
+
+### Building
+```bash
+# Library only
+cargo build --no-default-features
+
+# With CLI
+cargo build --features cli
+
+# With OpenRPC server
+cargo build --features openrpc
+```
+
+### Testing
+```bash
+cargo test --all-features
+```
+
+### Running
+```bash
+# Start supervisor with OpenRPC server
+RUST_LOG=info cargo run --features openrpc
+```
+
+## Dependencies
+
+### Core Dependencies
+- `tokio` - Async runtime
+- `redis` - Redis client for job queuing
+- `serde` - Serialization
+- `log` - Logging
+- `sal-service-manager` - Process management
+
+### Feature-Gated Dependencies
+- `jsonrpsee` - JSON-RPC server (openrpc feature)
+- `anyhow` - Error handling (openrpc feature)
+
+## Architecture Benefits
+
+1. **No Cyclic Dependencies**: Library and OpenRPC server are in the same crate, eliminating dependency cycles
+2. **Feature-Gated**: CLI and server functionality only compiled when needed
+3. **Clean Separation**: Library can be used independently without CLI dependencies
+4. **Conditional Compilation**: Rust's feature system ensures minimal dependencies for library users
+5. **Single Binary**: One supervisor binary with optional OpenRPC server integration
+
+## License
+
+[Add your license information here]