# OS Module - Quick Reference

## File System (fs)

```rhai
copy(src, dest)           // Copy file/dir
copy_bin(src)             // Copy to ~/hero/bin/
exist(path) -> bool       // Check if exists
find_file(dir, name)      // Find first file matching name
find_files(dir, name)     // Find all files matching name
find_dir(dir, name)       // Find first dir matching name
find_dirs(dir, name)      // Find all dirs matching name
delete(path)              // Delete file/dir recursively
mkdir(path)               // Create dir (with parents)
file_size(path) -> i64    // Get file size in bytes
rsync(src, dest)          // Sync directories
chdir(path)               // Change working directory
file_read(path)           // Read file content
file_write(path, content) // Write file (overwrite)
file_write_append(path, content) // Append to file
mv(src, dest)             // Move/rename file/dir
which(cmd) -> String      // Find command path (empty if not found)
cmd_ensure_exists(cmds)   // Ensure commands exist (comma-separated)
chmod_exec(path)          // Make file executable
```

## Download

```rhai
download(url, dest, min_kb)      // Download to dest, verify min size
download_file(url, dest, min_kb) // Same as download
download_install(url, min_kb)    // Download & install to ~/hero/bin/
```

## Package Management

```rhai
package_install(name)       // Install package
package_remove(name)        // Remove package
package_update()            // Update package lists
package_upgrade()           // Upgrade all packages
package_list() -> Array     // List installed packages
package_search(query)       // Search packages
package_is_installed(name)  // Check if installed
package_set_debug(bool)     // Enable debug output
package_platform()          // Get platform (brew/apt/apk)
```

## Platform Detection

```rhai
platform_is_osx() -> bool   // macOS?
platform_is_linux() -> bool // Linux?
platform_is_arm() -> bool   // ARM architecture?
platform_is_x86() -> bool   // x86_64 architecture?
platform_check_linux_x86()  // Assert Linux x86_64
platform_check_macos_arm()  // Assert macOS ARM
```

## Examples

```rhai
// Download and install binary
download_install("https://example.com/tool", 100);

// File operations
mkdir("/tmp/mydir");
file_write("/tmp/mydir/test.txt", "hello");
let content = file_read("/tmp/mydir/test.txt");
delete("/tmp/mydir");

// Find files
let configs = find_files("/etc", "*.conf");

// Platform-specific logic
if platform_is_osx() {
    package_install("wget");
}
```
