sal/process/README.md

# SAL Process Package

The `sal-process` package provides comprehensive functionality for managing and interacting with system processes across different platforms (Windows, macOS, and Linux).

## Features

- **Command Execution**: Run commands and scripts with flexible options
- **Process Management**: List, find, and kill processes
- **Cross-Platform**: Works consistently across Windows, macOS, and Linux
- **Builder Pattern**: Fluent API for configuring command execution
- **Rhai Integration**: Full support for Rhai scripting language
- **Error Handling**: Comprehensive error types and handling

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
sal-process = { path = "../process" }
```

## Usage

### Basic Command Execution

```rust
use sal_process::{run_command, run_silent};

// Run a command and capture output
let result = run_command("echo hello world")?;
println!("Output: {}", result.stdout);

// Run a command silently
let result = run_silent("ls -la")?;
```

### Builder Pattern

```rust
use sal_process::run;

// Use the builder pattern for more control
let result = run("echo test")
    .silent(true)
    .die(false)
    .log(true)
    .execute()?;
```

### Process Management

```rust
use sal_process::{which, process_list, process_get, kill};

// Check if a command exists
if let Some(path) = which("git") {
    println!("Git found at: {}", path);
}

// List all processes
let processes = process_list("")?;
println!("Found {} processes", processes.len());

// Find processes by pattern
let chrome_processes = process_list("chrome")?;

// Get a single process (errors if 0 or >1 matches)
let process = process_get("unique_process_name")?;

// Kill processes by pattern
kill("old_server")?;
```

### Multiline Scripts

```rust
let script = r#"
    echo "Starting script"
    export VAR="test"
    echo "Variable: $VAR"
    echo "Script complete"
"#;

let result = run_command(script)?;
```

## Rhai Integration

The package provides full Rhai integration for scripting:

```rhai
// Basic command execution
let result = run_command("echo hello");
print(result.stdout);

// Builder pattern
let result = run("echo test")
    .silent()
    .ignore_error()
    .execute();

// Process management
let git_path = which("git");
if git_path != () {
    print(`Git found at: ${git_path}`);
}

let processes = process_list("chrome");
print(`Found ${processes.len()} Chrome processes`);
```

## Error Handling

The package provides comprehensive error handling:

```rust
use sal_process::{run, RunError};

match run("some_command").execute() {
    Ok(result) => {
        if result.success {
            println!("Command succeeded: {}", result.stdout);
        } else {
            println!("Command failed with code: {}", result.code);
        }
    }
    Err(RunError::CommandExecutionFailed(e)) => {
        eprintln!("Failed to execute command: {}", e);
    }
    Err(e) => {
        eprintln!("Other error: {}", e);
    }
}
```

## Builder Options

The `run()` function returns a builder with these options:

- `.silent(bool)`: Suppress output to stdout/stderr
- `.die(bool)`: Return error if command fails (default: true)
- `.log(bool)`: Log command execution
- `.async_exec(bool)`: Run command asynchronously

## Cross-Platform Support

The package handles platform differences automatically:

- **Windows**: Uses `cmd.exe` for script execution
- **Unix-like**: Uses `/bin/bash` with `-e` flag for error handling
- **Process listing**: Uses appropriate tools (`wmic` on Windows, `ps` on Unix)
- **Command detection**: Uses `where` on Windows, `which` on Unix

## Testing

Run the test suite:

```bash
cargo test
```

The package includes comprehensive tests:
- Unit tests for all functionality
- Integration tests for real-world scenarios
- Rhai script tests for scripting integration
- Cross-platform compatibility tests

## Dependencies

- `tempfile`: For temporary script file creation
- `rhai`: For Rhai scripting integration
- `anyhow`: For error handling
- `sal-text`: For text processing utilities

Platform-specific dependencies:
- `nix` (Unix): For Unix-specific process operations
- `windows` (Windows): For Windows-specific process operations