Files
herolib/aiprompts/herolib_advanced/osal.md
2025-10-12 12:30:19 +03:00

683 lines
19 KiB
Markdown

# OSAL Core Module (incubaid.herolib.osal.core)
This document describes the core functionalities of the Operating System Abstraction Layer (OSAL) module, designed for platform-independent system operations in V.
```v
//example how to get started
import incubaid.herolib.osal.core as osal
osal.exec(...)!
```
## 1. Process Management
### `osal.exec(cmd: Command) !Job`
Executes a shell command with extensive configuration.
* **Parameters**:
* `cmd` (`Command` struct):
* `cmd` (string): The command string.
* `timeout` (int, default: 3600): Max execution time in seconds.
* `retry` (int): Number of retries on failure.
* `work_folder` (string): Working directory.
* `environment` (map[string]string): Environment variables.
* `stdout` (bool, default: true): Show command output.
* `stdout_log` (bool, default: true): Log stdout to internal buffer.
* `raise_error` (bool, default: true): Raise V error on failure.
* `ignore_error` (bool): Do not raise error, just report.
* `debug` (bool): Enable debug output.
* `shell` (bool): Execute in interactive shell.
* `interactive` (bool, default: true): Run in interactive mode.
* `async` (bool): Run command asynchronously.
* `runtime` (`RunTime` enum): Specify runtime (`.bash`, `.python`, etc.).
* **Returns**: `Job` struct (contains `status`, `output`, `error`, `exit_code`, `start`, `end`, `process`, `runnr`).
* **Error Handling**: Returns `JobError` with `error_type` (`.exec`, `.timeout`, `.args`).
### `osal.execute_silent(cmd string) !string`
Executes a command silently.
* **Parameters**: `cmd` (string): The command string.
* **Returns**: `string` (command output).
### `osal.execute_debug(cmd string) !string`
Executes a command with debug output.
* **Parameters**: `cmd` (string): The command string.
* **Returns**: `string` (command output).
### `osal.execute_stdout(cmd string) !string`
Executes a command and prints output to stdout.
* **Parameters**: `cmd` (string): The command string.
* **Returns**: `string` (command output).
### `osal.execute_interactive(cmd string) !`
### `osal.execute_ok(cmd string) bool`
Executes a command and returns `true` if the command exits with a zero status, `false` otherwise.
* **Parameters**: `cmd` (string): The command string.
* **Returns**: `bool`.
Executes a command in an interactive shell.
### `osal.exec_fast(cmd: CommandFast) !string`
Executes a command quickly, with options for profile sourcing and environment variables.
* **Parameters**:
* `cmd` (`CommandFast` struct):
* `cmd` (string): The command string.
* `ignore_error` (bool): Do not raise error on non-zero exit code.
* `work_folder` (string): Working directory.
* `environment` (map[string]string): Environment variables.
* `ignore_error_codes` ([]int): List of exit codes to ignore.
* `debug` (bool): Enable debug output.
* `includeprofile` (bool): Source the user's profile before execution.
* `notempty` (bool): Return an error if the output is empty.
* **Returns**: `string` (command output).
* **Parameters**: `cmd` (string): The command string.
### `osal.cmd_exists(cmd string) bool`
Checks if a command exists in the system's PATH.
* **Parameters**: `cmd` (string): The command name.
* **Returns**: `bool`.
### `osal.processmap_get() !ProcessMap`
Scans and returns a map of all running processes.
* **Returns**: `ProcessMap` struct (contains `processes` (`[]ProcessInfo`), `lastscan`, `state`, `pids`).
### `osal.processinfo_get(pid int) !ProcessInfo`
Retrieves detailed information for a specific process by PID.
* **Parameters**: `pid` (int): Process ID.
* **Returns**: `ProcessInfo` struct (contains `cpu_perc`, `mem_perc`, `cmd`, `pid`, `ppid`, `rss`).
### `osal.processinfo_get_byname(name string) ![]ProcessInfo`
Retrieves detailed information for processes matching a given name.
* **Parameters**: `name` (string): Process name (substring match).
* **Returns**: `[]ProcessInfo`.
### `osal.process_exists(pid int) bool`
Checks if a process with a given PID exists.
* **Parameters**: `pid` (int): Process ID.
* **Returns**: `bool`.
### `osal.processinfo_with_children(pid int) !ProcessMap`
Returns a process and all its child processes.
## 1.1. Done Context Management (`done.v`)
Functions for managing a "done" context or state using Redis.
* **`osal.done_set(key string, val string) !`**: Sets a key-value pair in the "done" context.
* **`osal.done_get(key string) ?string`**: Retrieves a value from the "done" context by key.
* **`osal.done_delete(key string) !`**: Deletes a key from the "done" context.
* **`osal.done_get_str(key string) string`**: Retrieves a string value from the "done" context by key (panics on error).
* **`osal.done_get_int(key string) int`**: Retrieves an integer value from the "done" context by key (panics on error).
* **`osal.done_exists(key string) bool`**: Checks if a key exists in the "done" context.
* **`osal.done_print() !`**: Prints all key-value pairs in the "done" context to debug output.
* **`osal.done_reset() !`**: Resets (deletes all keys from) the "done" context.
* **Parameters**: `pid` (int): Parent Process ID.
* **Returns**: `ProcessMap`.
### `osal.processinfo_children(pid int) !ProcessMap`
Returns all child processes for a given PID.
* **Parameters**: `pid` (int): Parent Process ID.
* **Returns**: `ProcessMap`.
### `osal.process_kill_recursive(args: ProcessKillArgs) !`
Kills a process and all its children by name or PID.
* **Parameters**:
* `args` (`ProcessKillArgs` struct):
* `name` (string): Process name.
* `pid` (int): Process ID.
### `osal.process_exists_byname(name string) !bool`
Checks if a process with a given name exists.
* **Parameters**: `name` (string): Process name (substring match).
* **Returns**: `bool`.
### `osal.whoami() !string`
Returns the current username.
* **Returns**: `string`.
## 2. Network Utilities
### `osal.ping(args: PingArgs) ! bool`
Checks host reachability.
* **Parameters**:
### `osal.ipaddr_pub_get_check() !string`
Retrieves the public IP address and verifies it is bound to a local interface.
* **Returns**: `string`.
### `osal.is_ip_on_local_interface(ip string) !bool`
Checks if a given IP address is bound to a local network interface.
* **Parameters**: `ip` (string): IP address to check.
* **Returns**: `bool`.
* `args` (`PingArgs` struct):
* `address` (string, required): IP address or hostname.
* `count` (u8, default: 1): Number of pings.
* `timeout` (u16, default: 1): Timeout in seconds per ping.
* `retry` (u8): Number of retry attempts.
* **Returns**: `PingResult` enum (`.ok`, `.timeout`, `.unknownhost`).
### `osal.tcp_port_test(args: TcpPortTestArgs) bool`
Tests if a TCP port is open on a given address.
* **Parameters**:
* `args` (`TcpPortTestArgs` struct):
* `address` (string, required): IP address or hostname.
* `port` (int, default: 22): TCP port number.
* `timeout` (u16, default: 2000): Total timeout in milliseconds.
* **Returns**: `bool`.
### `osal.ipaddr_pub_get() !string`
Retrieves the public IP address.
* **Returns**: `string`.
### `osal.is_ip_on_local_interface(ip string) !bool`
Checks if a given IP address is bound to a local network interface.
* **Parameters**: `ip` (string): IP address to check.
* **Returns**: `bool`.
## 3. File System Operations
### `osal.file_write(path string, text string) !`
Writes text content to a file.
* **Parameters**:
* `path` (string): File path.
* `text` (string): Content to write.
### `osal.file_read(path string) !string`
Reads content from a file.
* **Parameters**: `path` (string): File path.
* **Returns**: `string` (file content).
### `osal.dir_ensure(path string) !`
Ensures a directory exists, creating it if necessary.
* **Parameters**: `path` (string): Directory path.
### `osal.dir_delete(path string) !`
Deletes a directory if it exists.
* **Parameters**: `path` (string): Directory path.
### `osal.dir_reset(path string) !`
Deletes and then recreates a directory.
* **Parameters**: `path` (string): Directory path.
### `osal.rm(todelete string) !`
Removes files or directories.
* **Parameters**: `todelete` (string): Comma or newline separated list of paths (supports `~` for home directory).
### `osal.env_get_all() map[string]string`
Returns all existing environment variables as a map.
* **Returns**: `map[string]string`.
## 4. Environment Variables
## 4.1. Package Management (`package.v`)
Functions for managing system packages.
* **`osal.package_refresh() !`**: Updates the package list for the detected platform.
* **`osal.package_install(name_ string) !`**: Installs one or more packages.
* **`osal.package_remove(name_ string) !`**: Removes one or more packages.
### `osal.env_set(args: EnvSet)`
Sets an environment variable.
* **Parameters**:
* `args` (`EnvSet` struct):
* `key` (string, required): Environment variable name.
* `value` (string, required): Value to set.
* `overwrite` (bool, default: true): Overwrite if exists.
### `osal.env_unset(key string)`
Unsets a specific environment variable.
* **Parameters**: `key` (string): Environment variable name.
### `osal.env_unset_all()`
Unsets all environment variables.
### `osal.env_set_all(args: EnvSetAll)`
Sets multiple environment variables.
* **Parameters**:
* `args` (`EnvSetAll` struct):
* `env` (map[string]string): Map of key-value pairs.
* `clear_before_set` (bool): Clear all existing variables before setting.
* `overwrite_if_exists` (bool, default: true): Overwrite existing variables.
### `osal.env_get(key string) !string`
Retrieves the value of a specific environment variable.
* **Parameters**: `key` (string): Environment variable name.
* **Returns**: `string` (variable value).
### `osal.env_exists(key string) !bool`
Checks if an environment variable exists.
* **Parameters**: `key` (string): Environment variable name.
* **Returns**: `bool`.
### `osal.env_get_default(key string, def string) string`
Retrieves an environment variable or a default value if not found.
* **Parameters**:
* `key` (string): Environment variable name.
* `def` (string): Default value.
* **Returns**: `string`.
### `osal.load_env_file(file_path string) !`
Loads environment variables from a specified file.
* **Parameters**: `file_path` (string): Path to the environment file.
## 5. Command & Profile Management
### `osal.cmd_add(args: CmdAddArgs) !`
Adds (copies or symlinks) a binary to system paths and updates user profiles.
* **Parameters**:
* `args` (`CmdAddArgs` struct):
* `cmdname` (string): Name of the command (optional, derived from source if empty).
* `source` (string, required): Path to the binary.
* `symlink` (bool): Create a symlink instead of copying.
* `reset` (bool, default: true): Delete existing command if found.
### `osal.profile_path_add_hero() !string`
Ensures the `~/hero/bin` path is added to the user's profile.
* **Returns**: `string` (the `~/hero/bin` path).
### `osal.bin_path() !string`
Returns the preferred binary installation path (`~/hero/bin`).
* **Returns**: `string`.
### `osal.hero_path() !string`
Returns the `~/hero` directory path.
* **Returns**: `string`.
### `osal.usr_local_path() !string`
Returns `/usr/local` for Linux or `~/hero` for macOS.
* **Returns**: `string`.
### `osal.cmd_exists_profile(cmd string) bool`
Checks if a command exists in the system's PATH, considering the user's profile.
* **Parameters**: `cmd` (string): The command name.
* **Returns**: `bool`.
### `osal.profile_path_source() !string`
Returns a source statement for the preferred profile file (e.g., `. /home/user/.zprofile`).
* **Returns**: `string`.
### `osal.profile_path_source_and() !string`
Returns a source statement followed by `&&` for command chaining, or empty if profile doesn't exist.
* **Returns**: `string`.
### `osal.profile_path_add_remove(args: ProfilePathAddRemoveArgs) !`
Adds and/or removes paths from specified or preferred user profiles.
* **Parameters**:
* `args` (`ProfilePathAddRemoveArgs` struct):
* `paths_profile` (string): Comma/newline separated list of profile file paths (optional, uses preferred if empty).
* `paths2add` (string): Comma/newline separated list of paths to add.
* `paths2delete` (string): Comma/newline separated list of paths to delete.
* `allprofiles` (bool): Apply to all known profile files.
### `osal.cmd_path(cmd string) !string`
Returns the full path of an executable command using `which`.
* **Parameters**: `cmd` (string): Command name.
* **Returns**: `string` (full path).
### `osal.cmd_delete(cmd string) !`
Deletes commands from their found locations.
* **Parameters**: `cmd` (string): Command name.
### `osal.profile_paths_all() ![]string`
Lists all possible profile file paths in the OS.
* **Returns**: `[]string`.
### `osal.profile_paths_preferred() ![]string`
## 5.1. SSH Key Management (`ssh_key.v`)
Functions and structs for managing SSH keys.
### `struct SSHKey`
Represents an SSH key pair.
* **Fields**: `name` (string), `directory` (string).
* **Methods**:
* `public_key_path() !pathlib.Path`: Returns the path to the public key.
* `private_key_path() !pathlib.Path`: Returns the path to the private key.
* `public_key() !string`: Returns the content of the public key.
* `private_key() !string`: Returns the content of the private key.
### `struct SSHConfig`
Configuration for SSH key operations.
* **Fields**: `directory` (string, default: `~/.ssh`).
### `osal.get_ssh_key(key_name string, config SSHConfig) ?SSHKey`
Retrieves a specific SSH key by name.
* **Parameters**: `key_name` (string), `config` (`SSHConfig` struct).
* **Returns**: `?SSHKey` (optional SSHKey struct).
### `osal.list_ssh_keys(config SSHConfig) ![]SSHKey`
Lists all SSH keys in the specified directory.
* **Parameters**: `config` (`SSHConfig` struct).
* **Returns**: `[]SSHKey`.
### `osal.new_ssh_key(key_name string, config SSHConfig) !SSHKey`
Creates a new SSH key pair.
* **Parameters**: `key_name` (string), `config` (`SSHConfig` struct).
* **Returns**: `SSHKey`.
Lists preferred profile file paths based on the operating system.
* **Returns**: `[]string`.
### `osal.profile_path() !string`
Returns the most preferred profile file path.
* **Returns**: `string`.
## 6. System Information & Utilities
### `osal.platform() !PlatformType`
Identifies the operating system.
* **Returns**: `PlatformType` enum (`.unknown`, `.osx`, `.ubuntu`, `.alpine`, `.arch`, `.suse`).
### `osal.cputype() !CPUType`
Identifies the CPU architecture.
* **Returns**: `CPUType` enum (`.unknown`, `.intel`, `.arm`, `.intel32`, `.arm32`).
### `osal.is_linux() !bool`
Checks if the current OS is Linux.
* **Returns**: `bool`.
### `osal.is_osx() !bool`
Checks if the current OS is macOS.
* **Returns**: `bool`.
### `osal.is_ubuntu() !bool`
Checks if the current OS is Ubuntu.
* **Returns**: `bool`.
### `osal.is_osx_arm() !bool`
Checks if the current OS is macOS ARM.
* **Returns**: `bool`.
### `osal.is_linux_arm() !bool`
Checks if the current OS is Linux ARM.
* **Returns**: `bool`.
### `osal.is_osx_intel() !bool`
Checks if the current OS is macOS Intel.
* **Returns**: `bool`.
### `osal.is_linux_intel() !bool`
Checks if the current OS is Linux Intel.
* **Returns**: `bool`.
### `osal.hostname() !string`
Returns the system hostname.
* **Returns**: `string`.
### `osal.initname() !string`
Returns the init system name (e.g., `systemd`, `bash`, `zinit`).
* **Returns**: `string`.
### `osal.sleep(duration int)`
Pauses execution for a specified duration.
* **Parameters**: `duration` (int): Sleep duration in seconds.
### `osal.download(args: DownloadArgs) !pathlib.Path`
Downloads a file from a URL.
* **Parameters**:
* `args` (`DownloadArgs` struct):
* `url` (string, required): URL of the file.
* `name` (string): Optional, derived from filename if empty.
* `reset` (bool): Force download, remove existing.
* `hash` (string): Hash for verification.
* `dest` (string): Destination path.
* `timeout` (int, default: 180): Download timeout in seconds.
* `retry` (int, default: 3): Number of retries.
* `minsize_kb` (u32, default: 10): Minimum expected size in KB.
* `maxsize_kb` (u32): Maximum expected size in KB.
* `expand_dir` (string): Directory to expand archive into.
* `expand_file` (string): File to expand archive into.
* **Returns**: `pathlib.Path` (path to the downloaded file/directory).
### `osal.user_exists(username string) bool`
Checks if a user exists on the system.
* **Parameters**: `username` (string): Username to check.
* **Returns**: `bool`.
### `osal.user_id_get(username string) !int`
Retrieves the user ID for a given username.
* **Parameters**: `username` (string): Username.
* **Returns**: `int` (User ID).
### `osal.user_add(args: UserArgs) !int`
Adds a new user to the system.
* **Parameters**:
* `args` (`UserArgs` struct):
* `name` (string, required): Username to add.
* **Returns**: `int` (User ID of the added user).
## Enums & Structs
### `enum PlatformType`
Represents the detected operating system.
* Values: `unknown`, `osx`, `ubuntu`, `alpine`, `arch`, `suse`.
### `enum CPUType`
Represents the detected CPU architecture.
* Values: `unknown`, `intel`, `arm`, `intel32`, `arm32`.
### `enum RunTime`
Specifies the runtime environment for command execution.
* Values: `bash`, `python`, `heroscript`, `herocmd`, `v`.
### `enum JobStatus`
Status of an executed command job.
* Values: `init`, `running`, `error_exec`, `error_timeout`, `error_args`, `done`.
### `enum ErrorType`
Types of errors that can occur during job execution.
* Values: `exec`, `timeout`, `args`.
### `enum PingResult`
Result of a ping operation.
* Values: `ok`, `timeout`, `unknownhost`.
### `struct Command`
Configuration for `osal.exec` function. (See `osal.exec` parameters for fields).
### `struct Job`
Result object returned by `osal.exec`. (See `osal.exec` returns for fields).
### `struct JobError`
Error details for failed jobs.
### `struct PingArgs`
Arguments for `osal.ping` function. (See `osal.ping` parameters for fields).
### `struct TcpPortTestArgs`
Arguments for `osal.tcp_port_test` function. (See `osal.tcp_port_test` parameters for fields).
### `struct EnvSet`
Arguments for `osal.env_set` function. (See `osal.env_set` parameters for fields).
### `struct EnvSetAll`
Arguments for `osal.env_set_all` function. (See `osal.env_set_all` parameters for fields).
### `struct CmdAddArgs`
Arguments for `osal.cmd_add` function. (See `osal.cmd_add` parameters for fields).
### `struct ProfilePathAddRemoveArgs`
Arguments for `osal.profile_path_add_remove` function. (See `osal.profile_path_add_remove` parameters for fields).
### `struct ProcessMap`
Contains a list of `ProcessInfo` objects.
### `struct ProcessInfo`
Detailed information about a single process. (See `osal.processinfo_get` returns for fields).
### `struct ProcessKillArgs`
Arguments for `osal.process_kill_recursive` function. (See `osal.process_kill_recursive` parameters for fields).
### `struct DownloadArgs`
Arguments for `osal.download` function. (See `osal.download` parameters for fields).
### `struct UserArgs`
Arguments for `osal.user_add` function. (See `osal.user_add` parameters for fields).