feat: required-binary preflight check in main

Spec error-handling requirement (swaybg/wal always, qarma when GUI).
Caught by final integration review.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2 files changed, 38 insertions, 0 deletions

diff --git a/tests/wallp.bats b/tests/wallp.bats
index 0d6fc7e..d7edaec 100644
--- a/tests/wallp.bats
+++ b/tests/wallp.bats
@@ -267,3 +267,16 @@ teardown() {
   main --restore --theme tflag
   [ "$(cat "$HOME/.config/wallp/theme")" = "tflag" ]
 }
+
+@test "missing required binary errors before acting" {
+  unset WAYLAND_DISPLAY
+  rm -f "$STUB_DIR/swaybg"     # swaybg now absent
+  PATH="$STUB_DIR" run main --restore
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"swaybg"* ]]
+}
+
+@test "require_bins passes when all present" {
+  run require_bins
+  [ "$status" -eq 0 ]
+}
diff --git a/wallp b/wallp
index d021c2b..21f491b 100755
--- a/wallp
+++ b/wallp
@@ -262,6 +262,24 @@ Config: ~/.config/wallp/wallp.conf"
   fi
 }
 
+# Verify required external binaries are present. swaybg + wal always required;
+# qarma required only when GUI selection is needed (caller passes "gui").
+# notify-send is optional and not checked here.
+require_bins() {
+  local need_gui="${1:-}" bin
+  for bin in swaybg wal; do
+    if ! command -v "$bin" >/dev/null 2>&1; then
+      echo "wallp: required binary '$bin' not found in PATH" >&2
+      return 1
+    fi
+  done
+  if [ "$need_gui" = "gui" ] && ! command -v qarma >/dev/null 2>&1; then
+    echo "wallp: required binary 'qarma' not found in PATH" >&2
+    return 1
+  fi
+  return 0
+}
+
 main() {
   local action="" flag_theme="" set_args=()
   while [ "$#" -gt 0 ]; do
@@ -279,6 +297,13 @@ main() {
 
   if [ -z "$action" ]; then show_help; return 0; fi
 
+  # GUI (qarma) is needed only for an interactive --set with no H=/V= args.
+  local need_gui=""
+  if [ "$action" = "set" ] && [ "${#set_args[@]}" -eq 0 ] && [ -n "${WAYLAND_DISPLAY:-}" ]; then
+    need_gui="gui"
+  fi
+  require_bins "$need_gui" || return 1
+
   load_conf; local rc=$?
   if [ "$rc" -eq 10 ]; then return 0; fi   # bootstrapped, no change
   if [ "$rc" -ne 0 ]; then return 1; fi