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)
• Crates.io

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:

[dependencies]
herolib-os = "0.1.0"

Feature Flags

# 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

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

// 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:

./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

Process Module

Command Builder Methods:

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

GitTree Methods:

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:

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)

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)

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)

// 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:

hero-os rhaiexamples/os/01_filesystem.rhai

Building

# 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