testing improvements and doc

.github/workflows/shellspec.yml

@@ -0,0 +1,46 @@
+name: ShellSpec Tests
+
+on:
+  push:
+    branches: [main, dev, "feature/**"]
+  pull_request:
+    branches: [main, dev]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y zfsutils-linux man-db
+
+      - name: Install ShellSpec
+        run: curl -fsSL https://git.io/shellspec | sudo sh -s -- --yes --prefix /usr/local
+
+      - name: Create test user
+        run: |
+          sudo useradd -m -s /bin/bash testuser
+          echo 'testuser ALL=(ALL) NOPASSWD: /usr/bin/dd *, /usr/bin/rm -f /tmp/*, /usr/bin/truncate *, /usr/sbin/zpool *, /usr/sbin/zfs *' \
+            | sudo tee /etc/sudoers.d/testuser
+          sudo chown root:root /etc/sudoers.d/testuser
+          sudo chmod 0440 /etc/sudoers.d/testuser
+          sudo visudo -cf /etc/sudoers.d/testuser
+
+      - name: Copy repo for test user
+        run: |
+          sudo cp -r "$GITHUB_WORKSPACE" /home/testuser/zelta
+          sudo chown -R testuser:testuser /home/testuser/zelta
+
+      - name: Run ShellSpec tests
+        run: |
+          sudo -u testuser env \
+            SANDBOX_ZELTA_SRC_POOL=apool \
+            SANDBOX_ZELTA_TGT_POOL=bpool \
+            SANDBOX_ZELTA_SRC_DS=apool/treetop \
+            SANDBOX_ZELTA_TGT_DS=bpool/backups \
+            bash -c 'cd /home/testuser/zelta && shellspec'

.gitignore

@@ -1,8 +1,10 @@
+.*
 !.gitignore
 !.shellspec
+!.github/
+test/runners/test_generation/config/zelta_test_policy.conf
 *.swp
 *.swo
-.*
 doc/man?
 tmp
 hide.*
@@ -14,3 +16,4 @@ A*d
 retired/
 logs
 log
+ci/*

CHANGELOG.md

@@ -12,13 +12,15 @@ All notable changes to Zelta will be documented in this file.
 - **Commands**: `zelta revert` for in-place rollbacks via rename and clone.
 - **Commands**: `zelta rotate` for divergent version handling, evolved from original `--rotate` flag.
 - **Commands**: (Experimental) `zelta prune` identifies snapshots in `zfs destroy` range syntax based on replication state and a sliding window for exclusions.
+- **Installer**: (Experimental) Added a one-liner/pipe to shell installer option.
 - **Uninstaller**: Added `uninstall.sh` for clean removal of Zelta installations, including legacy paths from earlier betas.
 - **Core**: `zelta-args.awk` added as a separate data-driven argument preprocessor.
 - **Core**: `zelta-common.awk` library for centralized string and logging functions.
 - **Config**: Data-driven TSV configuration (`zelta-cmds.tsv`, `zelta-cols.tsv`, `zelta-json.tsv`, `zelta-opts.tsv`).
 - **Docs**: `zelta.env` expanded with comprehensive inline documentation and examples for all major configuration categories.
 - **Docs**: New man pages: `zelta-options(7)`, `zelta-revert(8)`, `zelta-rotate(8)`, `zelta-prune(8)`.
 - **Docs**: Added tool to sync man pages with the zelta.space wiki.
+- **Testing**: Added new advanced Shellspec-based testing suite.
 
 ### Changed
 - **Architecture**: Refactored all core scripts for maintainability and simpler logic.

README.md

@@ -1,17 +1,16 @@
 ![Zelta Logo](https://zelta.space/index/zelta-banner.svg)
-
 # The Zelta Backup and Recovery Suite
 *Version 1.1, 2026-01-20*
 
 ---
-
 > - **What's New:** Check [CHANGELOG.md](CHANGELOG.md) for the latest changes
-> - **Found a Bug?** Please [open an issue](https://github.com/bellhyve/zelta/issues)
-> - **Previous Release:** [March 2024, Zelta v1.0](https://github.com/bellhyve/zelta/tree/release/1.0)
-
+> - **Found a Bug?** Please [open an issue](https://github.com/bell-tower/zelta/issues)
+> - **Previous Release:** [March 2024, Zelta v1.0](https://github.com/bell-tower/zelta/tree/release/1.0)
+> 
+>       ![ShellSpec Tests](https://github.com/bell-tower/zelta/actions/workflows/shellspec.yml/badge.svg)
 ---
 
-[zelta.space](https://zelta.space) | [Documentation](https://zelta.space/en/home) | [GitHub](https://github.com/bellhyve/zelta)
+[zelta.space](https://zelta.space) | [Documentation](https://zelta.space/en/home) | [GitHub](https://github.com/bell-tower/zelta)
 
 **Zelta** provides bulletproof backups that meet strict compliance requirements while remaining straightforward to deploy and operate. It transforms complex backup and recovery operations into safe, auditable commands—protecting your data without requiring specialized expertise.
 
@@ -41,7 +40,7 @@ Written in portable Bourne shell and AWK, Zelta runs anywhere ZFS runs. No packa
 
 ### From Source (Recommended for Zelta 1.1)
 ```sh
-git clone https://github.com/bellhyve/zelta.git
+git clone https://github.com/bell-tower/zelta.git
 cd zelta
 sudo ./install.sh
 # The installer will guide you through setup.
@@ -55,11 +54,16 @@ pkg install zelta
 ```
 
 ### Experimental: One-Shot Install
+
+The following command clones Zelta from the `main` branch and launches the installer. Run this as a personal or backup user for a local, non-root installation. If you prefer a system-wide installation, run the command as root or via `sudo/doas`.
+
 ```sh
-curl -fsSL https://raw.githubusercontent.com/bellhyve/zelta/main/contrib/install-from-git.sh | sudo sh
+curl -fsSL https://raw.githubusercontent.com/bell-tower/zelta/main/contrib/install-from-git.sh | sh
 ```
 
-**Note:** This is experimental. For production use, we recommend cloning the repository and reviewing `install.sh` before running it.
+The installer will detect your privileges and guide you through adding the necessary environment variables to your shell profile.
+
+*Security Note: As with any script piped from the internet, we encourage you to [inspect the installer source](https://github.com/bell-tower/zelta/blob/main/contrib/install-from-git.sh) before execution.*
 
 ---
 
@@ -182,17 +186,17 @@ We welcome contributors who are passionate about data protection and recovery. B
 
 ### Contact
 
-We welcome questions, bug reports, and feature requests at [GitHub Issues](https://github.com/bellhyve/zelta/issues).
+We welcome questions, bug reports, and feature requests at [GitHub Issues](https://github.com/bell-tower/zelta/issues).
 
 For other inquiries including business questions, you can reach the Zelta team at Bell Tower via our [contact form](https://belltower.it/contact/).
 
 ### Conference Talks
 
-**BSDCan 2024: Zelta: A Safe and Powerful Approach to ZFS Replication**  
-By Daniel J. Bell  
+**BSDCan 2024: Zelta: A Safe and Powerful Approach to ZFS Replication** 
+By Daniel J. Bell 
 [Watch on YouTube](https://www.youtube.com/watch?v=_nmgQTs8wgE)
 
-**OpenZFS Summit 2025: Responsible Replication with Zelta**  
+**OpenZFS Summit 2025: Responsible Replication with Zelta** 
 [Watch on YouTube](https://www.youtube.com/watch?v=G3weooQqcXw)
 
 ### Bell Tower Services

contrib/install-from-git.sh

@@ -2,7 +2,7 @@
 # Zelta One-Shot Installer
 # Downloads latest Zelta from GitHub and runs install.sh
 #
-# Usage: curl -fsSL https://raw.githubusercontent.com/bellhyve/zelta/main/contrib/install-from-git.sh | sh
+# Usage: curl -fsSL https://raw.githubusercontent.com/bell-tower/zelta/main/contrib/install-from-git.sh | sh
 # Or specify branch: curl ... | sh -s -- --branch=develop
 
 set -e

doc/zelta-backup.md

@@ -73,7 +73,7 @@ _target_
 : Increase verbosity. Specify once for operational detail, twice (`-vv`) for debug output.
 
 **-q, \--quiet**
-: Quiet output. Specify once to suppress warnings, twice (`-qq`) to suppress errors.
+: Decrease log level. Specify once to suppress notices, twice (`-qq`) to suppress warnings.
 
 **-j, \--json**
 : Output results in JSON format. See **zelta-options(7)** for details.

doc/zelta-clone.md

@@ -36,7 +36,7 @@ _target_
 : Increase verbosity. Specify once for operational detail, twice (`-vv`) for debug output.
 
 **-q, \--quiet**
-: Quiet output. Specify once to suppress warnings, twice (`-qq`) to suppress errors.
+: Decrease log level. Specify once to suppress notices, twice (`-qq`) to suppress warnings.
 
 **-n, \--dryrun, \--dry-run**
 : Display `zfs` commands without executing them.

doc/zelta-match.md

@@ -18,7 +18,7 @@
 :    Increase verbosity. Specify once for operational detail and twice (-vv) for debug output.
 
 **-q, \--quiet**
-:    Quiet output. Specify once to suppress warnings and twice (-qq) to suppress errors.
+:    Decrease log level. Specify once to suppress notices, twice (-qq) to suppress warnings.
 
 **\--log-level**
 :    Specify a log level value 0-4: errors (0), warnings (1), notices (2, default), info (3, verbose), and debug (4).

doc/zelta-prune.md

@@ -46,7 +46,7 @@ _target_
 : Increase verbosity. Specify once for operational detail, twice (`-vv`) for debug output.
 
 **-q, \--quiet**
-: Quiet output. Specify once to suppress warnings, twice (`-qq`) to suppress errors.
+: Decrease log level. Specify once to suppress notices, twice (`-qq`) to suppress warnings.
 
 **-n, \--dryrun, \--dry-run**
 : Display `zfs` commands without executing them.

doc/zelta-revert.md

@@ -45,7 +45,7 @@ _endpoint_
 : Increase verbosity. Specify once for operational detail, twice (`-vv`) for debug output.
 
 **-q, \--quiet**
-: Quiet output. Specify once to suppress warnings, twice (`-qq`) to suppress errors.
+: Decrease log level. Specify once to suppress notices, twice (`-qq`) to suppress warnings.
 
 **-n, \--dryrun, \--dry-run**
 : Display `zfs` commands without executing them.

doc/zelta-rotate.md

@@ -56,7 +56,7 @@ _target_
 : Increase verbosity. Specify once for operational detail, twice (`-vv`) for debug output.
 
 **-q, \--quiet**
-: Quiet output. Specify once to suppress warnings, twice (`-qq`) to suppress errors.
+: Decrease log level. Specify once to suppress notices, twice (`-qq`) to suppress warnings.
 
 **-n, \--dryrun, \--dry-run**
 : Display `zfs` commands without executing them.

doc/zelta-snapshot.md

@@ -36,7 +36,7 @@ _endpoint_
 : Increase verbosity. Specify once for operational detail, twice (`-vv`) for debug output.
 
 **-q, \--quiet**
-: Quiet output. Specify once to suppress warnings, twice (`-qq`) to suppress errors.
+: Decrease log level. Specify once to suppress notices, twice (`-qq`) to suppress warnings.
 
 **-n, \--dryrun, \--dry-run**
 : Display `zfs` commands without executing them.

test/040_zelta_tests_spec.sh

@@ -1,12 +1,12 @@
 # Auto-generated ShellSpec test file
-# Generated at: 2026-02-12 13:28:34 -0500
+# Generated at: 2026-03-15 02:59:07 -0400
 # Source: 040_zelta_tests_spec
 # WARNING: This file was automatically generated. Manual edits may be lost.
 
 output_for_match_after_divergence() {
   while IFS= read -r line; do
     # normalize whitespace, remove leading/trailing spaces
-    normalized=$(echo "$line" | tr -s '[:space:]' ' ' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+    normalized=$(printf '%s' "$line" | tr -s '[:space:]' ' ' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
     case "$normalized" in
         "DS_SUFFIX MATCH SRC_LAST TGT_LAST INFO"|\
         "[treetop] @start @start @start up-to-date"|\
@@ -24,7 +24,8 @@ output_for_match_after_divergence() {
         "11 total datasets compared")
         ;;
       *)
-        printf "Unexpected line format: %s\n" "$line" >&2
+        printf "Unexpected line format : %s\n" "$line" >&2
+        printf "Comparing to normalized: %s\n" "$normalized" >&2
         return 1
         ;;
     esac
@@ -35,16 +36,17 @@ output_for_match_after_divergence() {
 output_for_rotate_after_divergence() {
   while IFS= read -r line; do
     # normalize whitespace, remove leading/trailing spaces
-    normalized=$(echo "$line" | tr -s '[:space:]' ' ' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+    normalized=$(printf '%s' "$line" | tr -s '[:space:]' ' ' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
     case "$normalized" in
         "source is written; snapshotting: @zelta_"*""|\
         "renaming '${SANDBOX_ZELTA_TGT_DS}' to '${SANDBOX_ZELTA_TGT_DS}_start'"|\
         "to ensure target is up-to-date, run: zelta backup ${SANDBOX_ZELTA_SRC_EP} ${SANDBOX_ZELTA_TGT_EP}"|\
         "no source: ${SANDBOX_ZELTA_TGT_DS}/sub1/kid"|\
-        "* sent, 10 streams received in * seconds")
+        ""*" sent, 10 streams received in "*" seconds")
         ;;
       *)
-        printf "Unexpected line format: %s\n" "$line" >&2
+        printf "Unexpected line format : %s\n" "$line" >&2
+        printf "Comparing to normalized: %s\n" "$normalized" >&2
         return 1
         ;;
     esac
@@ -55,7 +57,7 @@ output_for_rotate_after_divergence() {
 output_for_match_after_rotate() {
   while IFS= read -r line; do
     # normalize whitespace, remove leading/trailing spaces
-    normalized=$(echo "$line" | tr -s '[:space:]' ' ' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+    normalized=$(printf '%s' "$line" | tr -s '[:space:]' ' ' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
     case "$normalized" in
         "DS_SUFFIX MATCH SRC_LAST TGT_LAST INFO"|\
         "[treetop] @zelta_"*" @zelta_"*" @zelta_"*" up-to-date"|\
@@ -72,7 +74,8 @@ output_for_match_after_rotate() {
         "10 total datasets compared")
         ;;
       *)
-        printf "Unexpected line format: %s\n" "$line" >&2
+        printf "Unexpected line format : %s\n" "$line" >&2
+        printf "Comparing to normalized: %s\n" "$normalized" >&2
         return 1
         ;;
     esac
@@ -83,14 +86,15 @@ output_for_match_after_rotate() {
 output_for_backup_after_rotate() {
   while IFS= read -r line; do
     # normalize whitespace, remove leading/trailing spaces
-    normalized=$(echo "$line" | tr -s '[:space:]' ' ' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+    normalized=$(printf '%s' "$line" | tr -s '[:space:]' ' ' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
     case "$normalized" in
         "syncing 10 datasets"|\
         "10 datasets up-to-date"|\
-        "* sent, 3 streams received in * seconds")
+        ""*" sent, 3 streams received in "*" seconds")
         ;;
       *)
-        printf "Unexpected line format: %s\n" "$line" >&2
+        printf "Unexpected line format : %s\n" "$line" >&2
+        printf "Comparing to normalized: %s\n" "$normalized" >&2
         return 1
         ;;
     esac