...

packages/system/process/README.md

@@ -0,0 +1,178 @@
+# 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 = "0.1.0"
+```
+
+## 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