...

packages/system/virt/README.md

@@ -0,0 +1,176 @@
+# SAL Virt Package (`sal-virt`)
+
+The `sal-virt` package provides comprehensive virtualization and containerization tools for building, managing, and deploying containers and filesystem layers.
+
+## Installation
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+sal-virt = "0.1.0"
+```
+
+## Features
+
+- **Buildah**: OCI/Docker image building with builder pattern API
+- **Nerdctl**: Container lifecycle management with containerd
+- **RFS**: Remote filesystem mounting and layer management
+- **Cross-Platform**: Works across Windows, macOS, and Linux
+- **Rhai Integration**: Full support for Rhai scripting language
+- **Error Handling**: Comprehensive error types and handling
+
+## Modules
+
+### Buildah
+Container image building with Buildah, providing:
+- Builder pattern for container configuration
+- Image management and operations
+- Content operations (copy, add, run commands)
+- Debug mode support
+
+### Nerdctl
+Container management with Nerdctl, providing:
+- Container lifecycle management (create, start, stop, remove)
+- Image operations (pull, push, build, tag)
+- Network and volume management
+- Health checks and resource limits
+- Builder pattern for container configuration
+
+### RFS
+Remote filesystem operations, providing:
+- Mount/unmount operations for various filesystem types
+- Pack/unpack operations for filesystem layers
+- Support for Local, SSH, S3, WebDAV, and custom filesystems
+- Store specifications for different backends
+
+## Usage
+
+### Basic Buildah Example
+
+```rust
+use sal_virt::buildah::Builder;
+
+// Create a new builder
+let mut builder = Builder::new("my-container", "alpine:latest")?;
+
+// Configure the builder
+builder.set_debug(true);
+
+// Add content and run commands
+builder.copy("./app", "/usr/local/bin/app")?;
+builder.run(&["chmod", "+x", "/usr/local/bin/app"])?;
+
+// Commit the image
+let image_id = builder.commit("my-app:latest")?;
+```
+
+### Basic Nerdctl Example
+
+```rust
+use sal_virt::nerdctl::Container;
+
+// Create a container from an image
+let container = Container::from_image("web-app", "nginx:alpine")?
+    .with_port("8080:80")
+    .with_volume("/host/data:/app/data")
+    .with_env("ENV_VAR", "production")
+    .with_restart_policy("always");
+
+// Run the container
+let result = container.run()?;
+```
+
+### Basic RFS Example
+
+```rust
+use sal_virt::rfs::{RfsBuilder, MountType, StoreSpec};
+
+// Mount a remote filesystem
+let mount = RfsBuilder::new("user@host:/remote/path", "/local/mount", MountType::SSH)
+    .with_option("read_only", "true")
+    .mount()?;
+
+// Pack a directory
+let specs = vec![StoreSpec::new("file").with_option("path", "/tmp/store")];
+let pack_result = pack_directory("/source/dir", "/output/pack.rfs", &specs)?;
+```
+
+## Rhai Integration
+
+All functionality is available in Rhai scripts:
+
+```javascript
+// Buildah in Rhai
+let builder = bah_new("my-container", "alpine:latest");
+builder.copy("./app", "/usr/local/bin/app");
+builder.run(["chmod", "+x", "/usr/local/bin/app"]);
+
+// Nerdctl in Rhai
+let container = nerdctl_container_from_image("web-app", "nginx:alpine")
+    .with_port("8080:80")
+    .with_env("ENV", "production");
+container.run();
+
+// RFS in Rhai
+let mount_options = #{ "read_only": "true" };
+rfs_mount("user@host:/remote", "/local/mount", "ssh", mount_options);
+```
+
+## Dependencies
+
+- `sal-process`: For command execution
+- `sal-os`: For filesystem operations
+- `anyhow`: For error handling
+- `serde`: For serialization
+- `rhai`: For scripting integration
+
+## Testing
+
+The package includes comprehensive tests:
+
+```bash
+# Run all tests
+cargo test
+
+# Run specific test suites
+cargo test buildah_tests
+cargo test nerdctl_tests
+cargo test rfs_tests
+
+# Run Rhai integration tests
+cargo test --test rhai_integration
+```
+
+## Error Handling
+
+Each module provides its own error types:
+- `BuildahError`: For Buildah operations
+- `NerdctlError`: For Nerdctl operations  
+- `RfsError`: For RFS operations
+
+All errors implement `std::error::Error` and provide detailed error messages.
+
+## Platform Support
+
+- **Linux**: Full support for all features
+- **macOS**: Full support (requires Docker Desktop or similar)
+- **Windows**: Full support (requires Docker Desktop or WSL2)
+
+## Security
+
+- Credentials are handled securely and never logged
+- URLs with passwords are masked in logs
+- All operations respect filesystem permissions
+- Network operations use secure defaults
+
+## Configuration
+
+Most operations can be configured through environment variables:
+- `BUILDAH_DEBUG`: Enable debug mode for Buildah
+- `NERDCTL_DEBUG`: Enable debug mode for Nerdctl
+- `RFS_DEBUG`: Enable debug mode for RFS
+
+## License
+
+Apache-2.0