Pulse/docs/SCRIPT_LIBRARY.md

📜 Script Library Guide

This guide explains the shared Bash modules in scripts/lib/ used for building installer scripts.

📂 Structure

File	Purpose
common.sh	Logging, error handling, retry helpers, temp dirs.
http.sh	Curl/wget wrappers, GitHub release helpers.
systemd.sh	Systemd unit management helpers.

Conventions:

• Namespaces: Functions are exported as module::function (e.g., common::run).
• Bundling: make bundle-scripts inlines modules for distribution.
• Compatibility: Targets Bash 5 on Debian 11+ and Ubuntu LTS.

🦴 Script Skeleton

#!/usr/bin/env bash
set -euo pipefail

LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/lib" && pwd)"
# shellcheck source=../../scripts/lib/common.sh
source "${LIB_DIR}/common.sh"
# shellcheck source=../../scripts/lib/systemd.sh
source "${LIB_DIR}/systemd.sh"

common::init "$@"
common::require_command curl tar

main() {
  common::log_info "Starting installer..."
  common::temp_dir WORKDIR --prefix pulse-
  
  http::download --url "${URL}" --output "${WORKDIR}/pulse.tar.gz"
  
  systemd::create_service /etc/systemd/system/pulse.service <<'UNIT'
[Unit]
Description=Pulse Monitoring
UNIT

  systemd::enable_and_start pulse.service
}

main "$@"

🛠️ Best Practices

• Logging: Use common::log_info, common::log_warn, etc. They respect PULSE_LOG_LEVEL.
• Dry Run: Wrap mutating commands in common::run to support --dry-run.
• Testing: Use scripts/tests/run.sh for linting and scripts/tests/integration/ for scenarios.

📦 Bundling

1. Update scripts/bundle.manifest.
2. Run make bundle-scripts.
3. Verify dist/ artifacts.

Note: Never edit bundled artifacts manually. Always rebuild from source.