diff --git a/README.md b/README.md index 5172094..92a2d56 100644 --- a/README.md +++ b/README.md @@ -1,148 +1,136 @@ -# SAL (System Abstraction Layer) +# Herocode Herolib Rust Repository -**Version 0.1.0** - A modular Rust library for cross-platform system operations and automation. +## Overview -SAL provides a unified interface for system operations with Rhai scripting support through the `herodo` tool. +This repository contains the **Herocode Herolib** Rust library and a collection of scripts, examples, and utilities for building, testing, and publishing the SAL (System Abstraction Layer) crates. The repository includes: -## Installation +- **Rust crates** for various system components (e.g., `os`, `process`, `text`, `git`, `vault`, `kubernetes`, etc.). +- **Rhai scripts** and test suites for each crate. +- **Utility scripts** to automate common development tasks. -### Individual Packages (Recommended) +## Scripts + +The repository provides three primary helper scripts located in the repository root: + +| Script | Description | Typical Usage | +|--------|-------------|--------------| +| `scripts/publish-all.sh` | Publishes all SAL crates to **crates.io** in the correct dependency order. Handles version bumping, dependency updates, dry‑run mode, and rate‑limiting. | `./scripts/publish-all.sh [--dry-run] [--wait ] [--version ]` | +| `build_herodo.sh` | Builds the `herodo` binary from the `herodo` package and optionally runs a specified Rhai script. | `./build_herodo.sh [script_name]` | +| `run_rhai_tests.sh` | Executes all Rhai test suites across the repository, logging results and providing a summary. | `./run_rhai_tests.sh` | + +Below are detailed usage instructions for each script. + +--- + +## 1. `scripts/publish-all.sh` + +### Purpose + +- Publishes each SAL crate in the correct dependency order. +- Updates crate versions (if `--version` is supplied). +- Updates path dependencies to version dependencies before publishing. +- Supports **dry‑run** mode to preview actions without publishing. +- Handles rate‑limiting between crate publishes. + +### Options + +| Option | Description | +|--------|-------------| +| `--dry-run` | Shows what would be published without actually publishing. | +| `--wait ` | Wait time between publishes (default: 15 s). | +| `--version ` | Set a new version for all crates (updates `Cargo.toml` files). | +| `-h, --help` | Show help message. | + +### Example Usage ```bash -# Core functionality -cargo add sal-os sal-process sal-text sal-net +# Dry run – no crates will be published +./scripts/publish-all.sh --dry-run -# Infrastructure -cargo add sal-git sal-vault sal-kubernetes sal-virt +# Publish with a custom wait time and version bump +./scripts/publish-all.sh --wait 30 --version 1.2.3 -# Database clients -cargo add sal-redisclient sal-postgresclient sal-zinit-client - -# Scripting -cargo add sal-rhai +# Normal publish (no dry‑run) +./scripts/publish-all.sh ``` -### Meta-package with Features +### Notes + +- Must be run from the repository root (where `Cargo.toml` lives). +- Requires `cargo` and a logged‑in `cargo` session (`cargo login`). +- The script automatically updates dependencies in each crate’s `Cargo.toml` to use the new version before publishing. + +--- + +## 2. `build_herodo.sh` + +### Purpose + +- Builds the `herodo` binary from the `herodo` package. +- Copies the binary to a system‑wide location (`/usr/local/bin`) if run as root, otherwise to `~/hero/bin`. +- Optionally runs a specified Rhai script after building. + +### Usage ```bash -cargo add sal --features core # os, process, text, net -cargo add sal --features infrastructure # git, vault, kubernetes, virt -cargo add sal --features all # everything +# Build only +./build_herodo.sh + +# Build and run a specific Rhai script (e.g., `example`): +./build_herodo.sh example ``` -### Herodo Script Runner +### Details + +- The script changes to its own directory, builds the `herodo` crate (`cargo build`), and copies the binary. +- If a script name is provided, it looks for the script in: + - `src/rhaiexamples/.rhai` + - `src/herodo/scripts/.rhai` +- If the script is not found, the script exits with an error. + +--- + +## 3. `run_rhai_tests.sh` + +### Purpose + +- Runs **all** Rhai test suites across the repository. +- Supports both the legacy `rhai_tests` directory and the newer `*/tests/rhai` layout. +- Logs output to `run_rhai_tests.log` and prints a summary. + +### Usage ```bash -cargo install herodo -``` - -## Quick Start - -### Rust Library Usage - -```rust -use sal_os::fs; -use sal_process::run; - -fn main() -> Result<(), Box> { - let files = fs::list_files(".")?; - println!("Found {} files", files.len()); - - let result = run::command("echo hello")?; - println!("Output: {}", result.stdout); - Ok(()) -} -``` - -### Herodo Scripting - -```bash -# Create script -cat > example.rhai << 'EOF' -let files = find_files(".", "*.rs"); -print("Found " + files.len() + " Rust files"); - -let result = run("echo 'Hello from SAL!'"); -print("Output: " + result.stdout); -EOF - -# Run script -herodo example.rhai -``` - -## Available Packages - -| Package | Description | -|---------|-------------| -| [`sal-os`](https://crates.io/crates/sal-os) | Operating system operations | -| [`sal-process`](https://crates.io/crates/sal-process) | Process management | -| [`sal-text`](https://crates.io/crates/sal-text) | Text processing | -| [`sal-net`](https://crates.io/crates/sal-net) | Network operations | -| [`sal-git`](https://crates.io/crates/sal-git) | Git repository management | -| [`sal-vault`](https://crates.io/crates/sal-vault) | Cryptographic operations | -| [`sal-kubernetes`](https://crates.io/crates/sal-kubernetes) | Kubernetes management | -| [`sal-virt`](https://crates.io/crates/sal-virt) | Virtualization tools | -| [`sal-redisclient`](https://crates.io/crates/sal-redisclient) | Redis client | -| [`sal-postgresclient`](https://crates.io/crates/sal-postgresclient) | PostgreSQL client | -| [`sal-zinit-client`](https://crates.io/crates/sal-zinit-client) | Zinit process supervisor | -| [`sal-mycelium`](https://crates.io/crates/sal-mycelium) | Mycelium network client | -| [`sal-service-manager`](https://crates.io/crates/sal-service-manager) | Service management | -| [`sal-rhai`](https://crates.io/crates/sal-rhai) | Rhai scripting integration | -| [`sal`](https://crates.io/crates/sal) | Meta-crate with features | -| [`herodo`](https://crates.io/crates/herodo) | Script executor binary | - -## Building & Testing - -```bash -# Build all packages -cargo build --workspace - -# Run tests -cargo test --workspace - -# Run Rhai integration tests +# Run all tests ./run_rhai_tests.sh ``` -## Core Features +### Output -- **System Operations**: File/directory management, environment access, OS commands -- **Process Management**: Create, monitor, and control system processes -- **Containerization**: Buildah and nerdctl integration -- **Version Control**: Git repository operations -- **Database Clients**: Redis and PostgreSQL support -- **Networking**: HTTP, TCP, SSH connectivity utilities -- **Cryptography**: Key management, encryption, digital signatures -- **Text Processing**: String manipulation and templating -- **Scripting**: Rhai script execution via `herodo` +- Colored console output for readability. +- Log file (`run_rhai_tests.log`) contains full output for later review. +- Summary includes total modules, passed, and failed counts. +- Exit code `0` if all tests pass, `1` otherwise. -## Herodo Scripting +--- -`herodo` executes Rhai scripts with access to all SAL modules: +## General Development Workflow -```bash -herodo script.rhai # Run single script -herodo script.rhai arg1 arg2 # With arguments -herodo /path/to/scripts/ # Run all .rhai files in directory -``` +1. **Build**: Use `build_herodo.sh` to compile the `herodo` binary. +2. **Test**: Run `run_rhai_tests.sh` to ensure all Rhai scripts pass. +3. **Publish**: When ready to release, use `scripts/publish-all.sh` (with `--dry-run` first to verify). -### Example Script +## Prerequisites -```rhai -// File operations -let files = find_files(".", "*.rs"); -print("Found " + files.len() + " Rust files"); - -// Process execution -let result = run("echo 'Hello SAL!'"); -print("Output: " + result.stdout); - -// Redis operations -redis_set("status", "running"); -let status = redis_get("status"); -print("Status: " + status); -``` +- **Rust toolchain** (`cargo`, `rustc`) installed. +- **Rhai** interpreter (`herodo`) built and available. +- **Git** for version control. +- **Cargo login** for publishing to crates.io. ## License -Licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details. +See `LICENSE` for details. + +--- + +**Happy coding!**