Pulse/scripts/lib/README.md

Pulse Script Library

The scripts/lib directory houses shared Bash modules used by Pulse installation and maintenance scripts. The goal is to keep production installers modular and testable while still supporting bundled single-file artifacts for curl-based distribution.

Modules & Namespaces

• Each module lives in scripts/lib/<module>.sh.
• Public functions use the module::function namespace (common::log_info, proxmox::get_nodes, etc.).
• Internal helpers can be marked local or use a module::__helper prefix.
• Scripts should only rely on documented module:: APIs.

Using the Library

Development Mode

LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/lib" && pwd)"
if [[ -f "${LIB_DIR}/common.sh" ]]; then
  # shellcheck disable=SC1090
  source "${LIB_DIR}/common.sh"
fi

common::init "$@"
common::log_info "Starting installer..."

# Acquire a temp directory (automatically cleaned on exit)
common::temp_dir TMP_DIR --prefix pulse-install-
common::log_info "Working in ${TMP_DIR}"

Bundled Mode

Bundled scripts have the library concatenated into the file during the release process. The source guard remains but is a no-op because all functions are already defined.

Environment Variables

Variable	Description
PULSE_DEBUG	When set to 1, forces debug logging and enables additional diagnostics.
PULSE_LOG_LEVEL	Sets log level (debug, info, warn, error). Defaults to info.
PULSE_NO_COLOR	When 1, disables ANSI colors (used for non-TTY or forced monochrome).
PULSE_SUDO_CMD	Overrides the sudo command (e.g., /usr/bin/doas).
PULSE_FORCE_INTERACTIVE	Forces interactive behavior (treats script as running in a TTY).

common.sh API Reference

• common::init "$@" — Initializes logging, traps, and script metadata. Call once at script start.
• common::log_info "msg" — Logs informational messages to stdout.
• common::log_warn "msg" — Logs warnings to stderr.
• common::log_error "msg" — Logs errors to stderr.
• common::log_debug "msg" — Logs debug output (requires log level debug).
• common::fail "msg" [--code N] — Logs error and exits with optional status code.
• common::require_command cmd... — Verifies required commands exist; exits on missing dependencies.
• common::is_interactive — Returns success when stdin/stdout are TTYs or forced interactive.
• common::ensure_root [--allow-sudo] [--args "${COMMON__ORIGINAL_ARGS[@]}"] — Ensures root privileges, optionally re-executing via sudo.
• common::sudo_exec command... — Executes command with sudo, printing guidance if sudo is unavailable.
• common::run [--label desc] [--retries N] [--backoff "1 2"] -- cmd... — Executes a command with optional retries and dry-run support.
• common::run_capture [--label desc] -- cmd... — Runs a command and prints captured stdout; honors dry-run.
• common::temp_dir VAR [--prefix name] — Creates a temporary directory, assigns it to VAR, and registers cleanup (avoid command substitution so handlers persist).
• common::cleanup_push "description" "command" — Registers cleanup/rollback handler (LIFO order).
• common::cleanup_run — Executes registered cleanup handlers; automatically called on exit.
• common::set_dry_run true|false — Enables or disables dry-run mode for command wrappers.
• common::is_dry_run — Returns success when dry-run mode is active.

Bundling Workflow

1. Define modules under scripts/lib/.
2. Reference them from scripts using the development source guard.
3. Update scripts/bundle.manifest to list output artifacts and module order.
4. Run scripts/bundle.sh to generate bundled files under dist/.
5. Distribute bundled files (e.g., replace production installer).

Headers inserted during bundling (# === Begin: ... ===) mark module boundaries and aid debugging. The generated file includes provenance metadata with timestamp and manifest path.

• systemd.sh — safe wrappers around systemctl, unit creation helpers, and service lifecycle utilities.

• http.sh — download helpers, API call wrappers with retries, and GitHub release discovery.

• systemd::safe_systemctl args... — Run systemctl with timeout protection (container-friendly).

• systemd::service_exists name / systemd::detect_service_name … — Inspect available unit files.

• systemd::create_service path [mode] — Write a unit file from stdin (respects dry-run).

• systemd::enable_and_start name / systemd::restart name — Common service workflows.

• http::download --url URL --output FILE [...] — Robust curl/wget download helper with retries.

• http::api_call --url URL [...] — Token-authenticated API invocation; prints response body.

• http::get_github_latest_release owner/repo — Fetch latest GitHub release tag.

• http::parse_bool value — Normalize truthy/falsy strings.