Built-in Modules

ZSM provides several built-in modules that simplify script logic and reduce dependencies on external binaries. All built-ins are subject to the same permission system as external tools.

fs (Filesystem)

Requires: # :: perm fs

fs.move(src, dest)

Moves a file or directory. Handles cross-device moves automatically.

fs.move("/tmp/app", "~/.local/bin/app")

fs.mkdir(path)

Recursively creates directories (equivalent to mkdir -p).

fs.mkdir("~/.config/myapp")

fs.chmod(path, mode)

Changes file permissions using octal notation.

fs.chmod("~/.local/bin/app", "755")

web (Networking)

Requires: # :: perm net

web.download(url, dest)

Downloads a file to the specified destination. Uses a supervised curl call internally.

web.download("https://example.com/bin.tar.gz", "/tmp/bin.tar.gz")

web.get_json_field(url, field)

Fetches a JSON object and extracts a specific string field. Useful for release tags.

LATEST = web.get_json_field("https://api.github.com/...", "tag_name")

system (Host Info)

system.os()

Returns the host operating system (e.g. linux, macos).

system.arch()

Returns the host architecture (e.g. x86_64, aarch64).

system.arch_mapped()

Returns a normalized architecture name (e.g. amd64 instead of x86_64).

system.add_path(path)

Requires: # :: perm sys

Safely appends an export PATH=... line to the user's .bashrc, .zshrc, and .profile if it doesn't already exist.

system.add_path("~/.local/bin")

system.add_env(key, value)

Requires: # :: perm sys

Safely appends an environment variable export (e.g. export EDITOR="nvim") to the user's shell profiles.

system.add_env("EDITOR", "nvim")

system.add_alias(key, value)

Requires: # :: perm sys

Safely appends an alias (e.g. alias ll="ls -la") to the user's shell profiles.

system.add_alias("ll", "ls -la")

system.remove_path(path)

system.remove_env(key)

system.remove_alias(key)

These functions safely reverse the additions made by their counterparts. They are typically used inside an Uninstall Hook.

crypto (Cryptography)

Requires: # :: perm fs (to read the target file)

crypto.verify_sha256(path, expected_hash)

Native SHA-256 hash verification. Immediately aborts execution with a ChecksumMismatch error if the file's hash does not exactly match the expected value.

crypto.verify_sha256("/tmp/archive.tar.gz", "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")

crypto.verify_sha512(path, expected_hash)

Native SHA-512 hash verification.

ui (Interactive Interface)

Requires: # :: perm tty

ui.ask(prompt, default_value)

Securely prompts the user for input during execution. If the user presses Enter without typing anything, the default_value is returned.

INSTALL_DIR = ui.ask("Where should we install Zoi?", "~/.local/bin")

echo (Global)

echo(message)

Prints a message to stdout. Flushes automatically.

echo("Installation started...")