refactor wip

core/supervisor/examples/cli/README.md

@@ -0,0 +1,185 @@
+# Hero Supervisor CLI Example
+
+This example demonstrates how to use the `hive-supervisor` CLI tool for managing workers and jobs in the Hero ecosystem.
+
+## Prerequisites
+
+1. **Redis Server**: Make sure Redis is running on `localhost:6379`
+   ```bash
+   # Install Redis (macOS)
+   brew install redis
+   
+   # Start Redis
+   redis-server
+   ```
+
+2. **Zinit Process Manager**: Install and configure Zinit
+   ```bash
+   # Install Zinit (example for Linux/macOS)
+   # Follow Zinit installation instructions for your platform
+   ```
+
+3. **Worker Binaries**: The configuration references worker binaries that need to be available:
+   - `/usr/local/bin/osis_worker`
+   - `/usr/local/bin/sal_worker`
+   - `/usr/local/bin/v_worker`
+   - `/usr/local/bin/python_worker`
+
+   For testing purposes, you can create mock worker binaries or update the paths in `config.toml` to point to existing binaries.
+
+## Configuration
+
+The `config.toml` file contains the supervisor configuration:
+
+- **Global settings**: Redis URL and Zinit socket path
+- **Worker configurations**: Binary paths and environment variables for each worker type
+
+## Usage Examples
+
+### 1. Build the CLI
+
+```bash
+# From the supervisor directory
+cargo build --bin hive-supervisor --release
+```
+
+### 2. Worker Management
+
+```bash
+# Show help
+./target/release/hive-supervisor --config examples/cli/config.toml --help
+
+# List all configured workers
+./target/release/hive-supervisor --config examples/cli/config.toml workers list
+
+# Start all workers
+./target/release/hive-supervisor --config examples/cli/config.toml workers start
+
+# Start specific workers
+./target/release/hive-supervisor --config examples/cli/config.toml workers start osis_worker sal_worker
+
+# Check worker status
+./target/release/hive-supervisor --config examples/cli/config.toml workers status
+
+# Stop all workers
+./target/release/hive-supervisor --config examples/cli/config.toml workers stop
+
+# Restart specific worker
+./target/release/hive-supervisor --config examples/cli/config.toml workers restart osis_worker
+```
+
+### 3. Job Management
+
+```bash
+# Create a job with inline script
+./target/release/hive-supervisor --config examples/cli/config.toml jobs create \
+  --script 'print("Hello from OSIS worker!");' \
+  --script-type osis \
+  --caller-id "user123" \
+  --context-id "session456"
+
+# Create a job from file
+./target/release/hive-supervisor --config examples/cli/config.toml jobs create \
+  --file examples/cli/sample_script.rhai \
+  --script-type osis \
+  --caller-id "user123" \
+  --context-id "session456"
+
+# List all jobs
+./target/release/hive-supervisor --config examples/cli/config.toml jobs list
+
+# Check job status
+./target/release/hive-supervisor --config examples/cli/config.toml jobs status <JOB_ID>
+
+# View job logs
+./target/release/hive-supervisor --config examples/cli/config.toml jobs logs <JOB_ID>
+
+# Stop a job
+./target/release/hive-supervisor --config examples/cli/config.toml jobs stop <JOB_ID>
+```
+
+### 4. Interactive REPL Mode
+
+```bash
+# Enter REPL mode for OSIS scripts
+./target/release/hive-supervisor --config examples/cli/config.toml repl \
+  --caller-id "user123" \
+  --context-id "session456" \
+  --script-type osis \
+  --timeout 60
+
+# In REPL mode, you can:
+# - Type scripts directly and press Enter to execute
+# - Type 'help' for available commands
+# - Type 'exit' or 'quit' to leave REPL mode
+```
+
+### 5. Verbose Logging
+
+```bash
+# Enable debug logging
+./target/release/hive-supervisor --config examples/cli/config.toml -v workers status
+
+# Enable trace logging
+./target/release/hive-supervisor --config examples/cli/config.toml -vv workers status
+
+# Disable timestamps
+./target/release/hive-supervisor --config examples/cli/config.toml --no-timestamp workers status
+```
+
+## Sample Scripts
+
+The `sample_scripts/` directory contains example scripts for different worker types:
+
+- `hello_osis.rhai` - Simple OSIS/HeroScript example
+- `system_sal.rhai` - SAL system operation example
+- `math_v.v` - V language calculation example
+- `data_python.py` - Python data processing example
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Redis Connection Error**
+   - Ensure Redis is running: `redis-cli ping`
+   - Check the Redis URL in `config.toml`
+
+2. **Zinit Socket Error**
+   - Verify Zinit is running and the socket path is correct
+   - Check permissions on the socket file
+
+3. **Worker Binary Not Found**
+   - Update binary paths in `config.toml` to match your system
+   - Ensure worker binaries are executable
+
+4. **Permission Denied**
+   - Check file permissions on configuration and binary files
+   - Ensure the user has access to the Zinit socket
+
+### Debug Mode
+
+Run with verbose logging to see detailed operation information:
+
+```bash
+RUST_LOG=debug ./target/release/hive-supervisor --config examples/cli/config.toml -vv workers status
+```
+
+## Configuration Customization
+
+You can customize the configuration for your environment:
+
+1. **Update Redis URL**: Change `redis_url` in the `[global]` section
+2. **Update Zinit Socket**: Change `zinit_socket_path` for your Zinit installation
+3. **Worker Paths**: Update binary paths in worker sections to match your setup
+4. **Environment Variables**: Add or modify environment variables for each worker type
+
+## Integration with Hero Ecosystem
+
+This CLI integrates with the broader Hero ecosystem:
+
+- **Job Queue**: Uses Redis for job queuing and status tracking
+- **Process Management**: Uses Zinit for worker lifecycle management
+- **Script Execution**: Supports multiple script types (OSIS, SAL, V, Python)
+- **Monitoring**: Provides real-time status and logging capabilities
+
+For more information about the Hero ecosystem, see the main project documentation.