# herolib-os

[![Crates.io](https://img.shields.io/crates/v/herolib-os.svg)](https://crates.io/crates/herolib-os)
[![Documentation](https://docs.rs/herolib-os/badge.svg)](https://docs.rs/herolib-os)

Unified system utilities for Rust and Rhai scripting, providing OS operations, process management, virtualization, git, and Kubernetes management.

## Documentation

- [API Documentation (docs.rs)](https://docs.rs/herolib-os)
- [Crates.io](https://crates.io/crates/herolib-os)

## Features

- **OS Module** - Filesystem operations, platform detection, environment management
- **Process Module** - Command execution with builder pattern, process management
- **Git Module** - Repository management, URL parsing, git tree organization
- **Virt Module** - Container building (Buildah), container management (Nerdctl), remote filesystems (RFS)
- **Kubernetes Module** - Cluster management, pod operations, resource handling (optional)
- **Rhai Integration** - Full scripting support for all modules
- **Interactive REPL** - `hero-os` binary for testing and scripting

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
herolib-os = "0.1.0"
```

### Feature Flags

| Feature | Description |
|---------|-------------|
| `rhai` | Rhai scripting support (default) |
| `repl` | Interactive REPL binary |
| `kubernetes` | Kubernetes cluster management |
| `full` | All features enabled |

```toml
# With Kubernetes support
herolib-os = { version = "0.1.0", features = ["kubernetes"] }

# All features
herolib-os = { version = "0.1.0", features = ["full"] }
```

## Quick Start

### Rust API

```rust
use herolib_os::os::{exist, file_read, file_write};
use herolib_os::process::run;

fn main() -> anyhow::Result<()> {
    // Execute a command
    let result = run("ls -la")?;
    println!("Output: {}", result.stdout);

    // File operations
    if exist("/tmp/myfile.txt") {
        let content = file_read("/tmp/myfile.txt")?;
        println!("Content: {}", content);
    }

    file_write("/tmp/newfile.txt", "Hello, World!")?;

    Ok(())
}
```

### Rhai Scripting

```rhai
// Execute commands
let output = run("ls -la");
print(output);

// File operations
if exist("/tmp/myfile.txt") {
    let content = file_read("/tmp/myfile.txt");
    print(content);
}

// Platform detection
print("OS: " + os_name());
print("Arch: " + os_arch());

// Command builder pattern
let result = cmd("curl")
    .arg("-s")
    .arg("https://api.example.com")
    .silent()
    .execute();
```

## Interactive REPL

Build and run the interactive REPL:

```bash
./build.sh
hero-os
```

REPL features:
- Tab completion for all functions
- Syntax highlighting
- Command history
- Script loading with `:load filename.rhai`
- Scope inspection with `:scope`

```
╔═══════════════════════════════════════════════════════════════════╗
║                         HERO-OS                                   ║
║               System Utilities REPL v0.1.0                        ║
╚═══════════════════════════════════════════════════════════════════╝

Type :help for available commands, :quit to exit

hero> run("uname -a")
Darwin myhost 24.6.0 Darwin Kernel Version 24.6.0 ...

hero> os_name()
macos

hero> /load rhaiexamples/os/01_filesystem.rhai
```

## Module Reference

### OS Module

| Function | Description |
|----------|-------------|
| `exist(path)` | Check if file/directory exists |
| `file_read(path)` | Read file contents |
| `file_write(path, content)` | Write content to file |
| `file_size(path)` | Get file size in bytes |
| `delete(path)` | Delete file or directory |
| `mkdir(path)` | Create directory |
| `copy(src, dest)` | Copy file or directory |
| `mv(src, dest)` | Move/rename file or directory |
| `os_name()` | Get OS name (linux, macos, windows) |
| `os_arch()` | Get architecture (x86_64, aarch64) |
| `which(cmd)` | Find command in PATH |
| `env_get(name)` | Get environment variable |
| `env_set(name, value)` | Set environment variable |

### Process Module

| Function | Description |
|----------|-------------|
| `run(cmd)` | Execute command, return stdout |
| `cmd(cmd)` | Create command builder |
| `process_list()` | List running processes |
| `process_get(pid)` | Get process by PID |
| `process_kill(pid)` | Kill process by PID |

**Command Builder Methods:**
```rhai
cmd("curl")
    .arg("-s")              // Add argument
    .args(["-H", "Accept: application/json"])
    .env("TOKEN", "xxx")    // Set environment variable
    .cwd("/tmp")            // Set working directory
    .silent()               // Suppress output
    .ignore_error()         // Don't fail on non-zero exit
    .execute()              // Run and return CommandResult
```

### Git Module

| Function | Description |
|----------|-------------|
| `parse_git_url_extended(url)` | Parse git URL into components |
| `git_tree_new(path)` | Create git tree manager |
| `git_clone(url)` | Clone repository |

**GitTree Methods:**
```rhai
let tree = git_tree_new("/repos");
tree.list()                    // List all repositories
tree.find("*pattern*")         // Find matching repos
tree.get(name)                 // Get specific repo
tree.clone_repo(url)           // Clone repository
tree.get_path(url)             // Clone and return path
tree.get_path_pull(url)        // Clone, pull, return path
```

**GitRepo Methods:**
```rhai
repo.path()         // Get local path
repo.has_changes()  // Check for uncommitted changes
repo.pull()         // Pull from remote
repo.reset()        // Reset local changes
repo.commit(msg)    // Commit changes
repo.push()         // Push to remote
```

### Virt Module

#### Buildah (Container Image Building)

```rhai
let image = bah("mycontainer", "ubuntu:22.04")
    .run("apt update && apt install -y nginx")
    .copy("./config", "/etc/nginx/")
    .write("Hello", "/var/www/html/index.html")
    .entrypoint("/usr/sbin/nginx")
    .cmd("-g 'daemon off;'")
    .commit("myimage:latest");
```

#### Nerdctl (Container Management)

```rhai
let container = nerdctl_container_from_image("web", "nginx:latest")
    .with_port("8080:80")
    .with_volume("/data:/var/www/html")
    .with_env("NGINX_HOST", "localhost")
    .with_memory_limit("512m")
    .build();

container.exec("nginx -t");
container.logs();
container.stop();
```

#### RFS (Remote Filesystem)

```rhai
// Mount remote filesystem
rfs_mount("/source", "/mnt/target", "ssh", #{
    "host": "server.example.com",
    "user": "admin"
});

// Pack/unpack layers
rfs_pack("/app", "/backup/app.layer", "file:path=/store");
rfs_unpack("/backup/app.layer", "/restored");
```

## Examples

See the `rhaiexamples/` directory for comprehensive examples:

```
rhaiexamples/
├── os/           # Filesystem and platform operations
├── process/      # Command execution and process management
├── git/          # Repository and URL handling
└── virt/         # Container and filesystem virtualization
```

Run examples with the REPL:

```bash
hero-os rhaiexamples/os/01_filesystem.rhai
```

## Building

```bash
# Build with REPL support
./build.sh

# Build with all features
cargo build --release --features full

# Run tests
cargo test

# Generate documentation
cargo doc --no-deps --open
```

## Requirements

- Rust 1.92.0 or later
- Edition 2024

### Optional Runtime Dependencies

- **Buildah** - For container image building
- **Nerdctl/Containerd** - For container management
- **Git** - For repository operations

## License

Apache-2.0
