📥 ZSHAND Installer Development Guide¶

📋 This guide covers how installers work, how to add a new platform, and package management conventions.

🧠 Philosophy

Installers should be idempotent, non-destructive, and informative. Running an installer twice should produce the same result. Always check before installing and report what was done.

🏗️ Architecture¶

📁 Directory Structure¶

installers/
├── 📋 README.md                      This guide (overview)
├── 📥 setup.zsh                      Bootstrap script (source — edit this)
├── 📥 debian.sh                      Debian installer (bash)
├── 📥 ubuntu.sh                      Ubuntu installer (bash)
├── 📥 wsl.sh                         WSL installer (bash)
├── 📥 manjaro.zsh                    Manjaro/Arch installer (zsh)
├── 📥 osx.zsh                        macOS installer (zsh)
├── 📥 manjaro-optional-installer.zsh Optional packages for Manjaro
├── 📥 Install-zshand.ps1            PowerShell installer (Windows/WSL)
├── 📦 general/                       Cross-platform utilities
│   ├── gum_helpers.sh               Shared gum TUI helpers (bash/zsh)
│   ├── environment.zsh              Environment setup
│   ├── links.zsh                    Symlink management
│   ├── logger.zsh                   Installer logging
│   ├── permissions.zsh              File permissions
│   └── required_dirs.zsh           Required directory creation
├── 📦 packages/                      Package lists by platform
│   ├── debian-packages.zsh          Debian required packages
│   ├── debian-optional.zsh          Debian optional packages
│   ├── manjaro-packages.zsh         Manjaro required packages
│   └── manjaro-optional.zsh         Manjaro optional packages
└── 🔧 utilities/                     Tool-specific installers
    ├── atuin-setup.zsh              Atuin history sync setup
    └── powershell-linux.zsh         PowerShell Core on Linux

Note: The top-level setup.zsh is a compiled single-file version (auto-generated by just setup). Edit installers/setup.zsh instead.

🔄 How Installers Are Called¶

setup.zsh (compiled)  ←  built from installers/setup.zsh + gum_helpers.sh
  │
  ├── Detects OS (from /etc/os-release or user selection)
  │
  ├── Looks for: installers/${os_id}.sh  OR  installers/${os_id}.zsh
  │
  └── Runs the matching installer via bash or zsh

📝 Writing a New Installer¶

🧱 Template¶

#!/usr/bin/env bash
# ── ${os_id}.sh — ZSHAND system installer for ${OS_NAME} ───────────────────
#
# Called by setup.zsh during first-time framework installation.
# Installs system dependencies required by the ZSHAND framework.
#
# USAGE:
#   bash installers/${os_id}.sh
#
# ─────────────────────────────────────────────────────────────────────────────

set -euo pipefail

echo "📦 Installing ZSHAND dependencies for ${OS_NAME}..."

# ── Required Packages ───────────────────────────────────────────────────────

REQUIRED=(
    zsh
    git
    curl
    jq
    fzf
    ripgrep
    fd-find
    bat
    eza
)

echo "📋 Installing required packages..."
for pkg in "${REQUIRED[@]}"; do
    if command -v "$pkg" &>/dev/null || dpkg -l "$pkg" &>/dev/null 2>&1; then
        echo "  ✓ $pkg (already installed)"
    else
        echo "  📥 Installing $pkg..."
        sudo apt install -y "$pkg" 2>/dev/null || echo "  ⚠️  Failed: $pkg"
    fi
done

# ── Optional Packages ──────────────────────────────────────────────────────

OPTIONAL=(
    htop
    duf
    tree
    micro
)

echo ""
echo "📋 Installing optional packages..."
for pkg in "${OPTIONAL[@]}"; do
    if command -v "$pkg" &>/dev/null; then
        echo "  ✓ $pkg (already installed)"
    else
        echo "  📥 Installing $pkg..."
        sudo apt install -y "$pkg" 2>/dev/null || echo "  ⚠️  Skipped: $pkg"
    fi
done

echo ""
echo "✓ ${OS_NAME} system dependencies installed."

📏 Rules¶

Idempotent — safe to run multiple times
Check before install — skip if already present
Report status — show ✓ for existing, 📥 for installing, ⚠️ for failures
Non-fatal failures — optional packages can fail silently
No interactive prompts — use -y flags for package managers
Separate required/optional — clearly distinguish must-have from nice-to-have

📦 Package Lists¶

Package lists live in installers/packages/ as zsh arrays:

# packages/debian-packages.zsh
# Required packages for Debian/Ubuntu

typeset -ga ZSHAND_REQUIRED_PACKAGES=(
    zsh
    git
    curl
    jq
    fzf
    ripgrep        # provides rg
    fd-find        # provides fd (may need alias)
    bat            # may be batcat on Debian
    eza
)

🔄 Package Name Mapping¶

Some tools have different package names across distros:

Tool	Debian/Ubuntu	Arch/Manjaro	Homebrew
`fd`	`fd-find`	`fd`	`fd`
`bat`	`bat` (or `batcat`)	`bat`	`bat`
`rg`	`ripgrep`	`ripgrep`	`ripgrep`
`eza`	`eza` (PPA)	`eza`	`eza`
`wl-copy`	`wl-clipboard`	`wl-clipboard`	N/A

🧪 Testing Installers¶

✅ Manual Testing¶

# Test in a fresh container
docker run -it debian:latest bash
apt update && apt install -y curl git zsh
# Clone and run
git clone <repo> ~/zshand && cd ~/zshand
bash installers/debian.sh

✅ Verification¶

After installation, run auditenv to verify:

auditenv  # Checks all required tools are present and meet version requirements

The minimum versions are defined in dependency-version-reqs.toml.

🌐 Adding a New Platform¶

Create the installer: installers/<os_id>.sh or .zsh
Create package lists: installers/packages/<os_id>-packages.zsh
Update OS detection in installers/setup.zsh (if the OS isn't auto-detected), then run just setup
Test in a fresh environment (container or VM)
Update dependency-version-reqs.toml if minimum versions differ
Document any platform-specific quirks

Document	Purpose
🏗️ ARCHITECTURE.md	Framework structure and setup flow
🤝 CONTRIBUTING.md	Contribution workflow
👤 USER_CONFIG.md	Post-install configuration