Module utils 

General utility functions.

Functions

ask_for_confirmation

Prompts the user for confirmation (y/N) unless the yes flag is set.

build_blocking_http_client

Builds a blocking HTTP client with a custom timeout.

check_license

Validates a package license against SPDX and organizational policies.

command_exists

Checks if a command exists in the system’s PATH.

confirm_untrusted_source

Prompts the user to confirm installation from an untrusted (non-official) source.

copy_dir_all

Recursively copies all files and subdirectories from source to destination.

expand_placeholders

Expands standard Zoi path placeholders (e.g. ${pkgstore}, ${usrhome}) in a string.

expand_tilde

Expands the ~ character to the user’s home directory.

format_bytes

Formats a byte count into a human-readable string (e.g. “1.24 MiB”).

format_size_diff

Formats a size difference into a signed human-readable string (e.g. “+50 B”).

generate_package_id

Generates a unique, origin-aware ID for a package.

generate_versioned_package_id

Generates a unique ID for a package including its version.

get_all_available_package_managers

Scans the system for all supported package managers.

get_cpu_info

Returns a short description of the system’s CPU.

get_current_shell

Detects and returns the current shell being used.

get_db_base_dir

Returns the root directory of the package database for a given scope.

get_db_root

Returns the root directory for the package database.

get_desktop_environment

Returns the name of the current desktop environment (e.g. “gnome”, “kde”).

get_display_server

Returns the name of the current display server (e.g. “wayland”, “x11”).

get_distro_version

Returns the version of the current distribution.

get_git_base_dir

Returns the root directory for Git repositories for a given scope.

get_gpu_info

Returns a short description of the system’s GPU.

get_http_client

Creates an HTTP client with Zoi’s default configuration.

get_init_system

Returns the name of the system’s init system (e.g. “systemd”, “openrc”).

get_kernel_version

Returns the version of the operating system kernel.

get_linux_distribution

Returns the ID of the current Linux distribution (e.g. “debian”, “fedora”).

get_linux_distribution_info

Retrieves information about the current Linux distribution from /etc/os-release.

get_linux_distro_family

Detects the general family of a Linux distribution (e.g. “debian”, “arch”, “fedora”).

get_native_package_manager

Identifies the primary package manager for the current operating system.

get_package_dir_name

Creates the directory name for the package in the store. Format: {hash}-{name}

get_platform

Returns a standard Zoi platform identifier (e.g. “linux-amd64”, “windows-arm64”).

get_privilege_escalator

Returns the name of the available privilege escalation tool (e.g. “sudo”, “doas”).

get_store_base_dir

Returns the root directory of the package store for a given scope.

get_user_home

Returns the home directory of the current user, or the original user if run via sudo or doas.

is_admin

Checks if the current process has administrative privileges.

is_mini_mode

Returns true if Zoi is running in “Mini” mode (lightweight, zero-sync).

is_platform_compatible

Checks if a target platform is compatible with a list of allowed platforms.

is_safe_path

Verifies that a given path is “Safe” and doesn’t attempt to escape the base directory.

is_zoios

Returns true if the current system is a ZoiOS-based distribution (like Parlex).

resolve_fallback_scope

Resolves the default installation scope based on the current environment.

retry_backoff_sleep

Performs a jittered exponential backoff sleep.

run_shell_command

Executes a shell command and returns an error if it fails.

run_shell_command_quietly

Executes a shell command quietly (suppressing output) and returns an error if it fails.

set_path_owner

Sets the owner and group for a file or directory (Unix only).

set_path_read_only

Recursively sets a directory and its contents to be read-only.

set_path_writable

Recursively ensures a directory and its contents are writable.

symlink_dir

Creates a symbolic link for a directory, handling platform-specific requirements.

symlink_file

Creates a symbolic link for a file, handling platform-specific requirements.