herolib-os

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

Documentation

• API Documentation (docs.rs)
• Crates.io

Features

• OS Module - Filesystem operations, platform detection, package management, file downloads
• Process Module - Command execution with builder pattern, process management
• Git Module - Repository management, URL parsing, git tree organization
• Network Module - TCP connectivity, HTTP/HTTPS operations, SSH support with key management and file transfers
• 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 REPL support
herolib-os = { version = "0.1.0", features = ["repl"] }

# 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());

// TCP and HTTP connectivity checks
let is_open = net_tcp_check("example.com", 443);
let is_reachable = net_http_check("https://example.com");

// Network operations
let is_pingable = net_tcp_ping("example.com");

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

Network Module

SSH Connection:

let conn = SshConnection::new()
    .host("example.com")
    .user("ubuntu")
    .port(22)
    .connect();

let (code, output) = conn.execute("whoami");

SSH Key Management:

let keygen = SshKeyGenerator::new("/tmp/my_key")
    .key_type(Ed25519);
keygen.generate();

let auth_mgr = AuthorizedKeysManager::new(conn);
auth_mgr.add_key("/path/to/id_rsa.pub");

File Transfer (SSH/Rsync):

let transfer = FileTransferOps::new(conn);
transfer.upload("/local/file", "/remote/path");
transfer.download("/remote/file", "/local/path");

Examples

See the rhaiexamples/ directory for comprehensive examples:

rhaiexamples/
├── os/           # Filesystem, platform detection, package management
├── process/      # Command execution and process management
├── git/          # Repository management and URL handling
├── net/          # TCP, HTTP, and network connectivity
└── ssh/          # SSH connections and file transfer

Run examples with the REPL:

hero-os rhaiexamples/os/01_filesystem.rhai
hero-os rhaiexamples/net/01_tcp_check.rhai
hero-os rhaiexamples/git/01_url_parsing.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

• Git - For repository operations and cloning
• SSH/OpenSSH - For SSH operations and file transfers
• curl - For HTTP operations (recommended)
• rsync - For efficient SSH file transfers (recommended)

License

Apache-2.0