From b280bd02d736c51e4771e3e9704c38f59ddb2d62 Mon Sep 17 00:00:00 2001
From: Gabriel Brown <gbrown@ksensetech.com>
Date: Fri, 21 Aug 2026 02:56:24 -0400
Subject: [PATCH] Let the Home Assistant contract skip a server that is not
 there

It already meant to skip when no token was configured, and could not: the helper
exits 2 for any catalog it cannot complete, so `set -e` aborted at the capture
before the skip was reached. The contract failed with no output at all, which
reads as a crash rather than as a skip, and the branch written to prevent that
had never once run.

So the status is taken deliberately, and there are now two skips rather than
one. No token is not a defect in Panama. Neither is a bridge that does not
answer -- off the network, VPN down, the server asleep -- which is the same
reasoning the extras contract already uses for dnf and Flathub being
unreachable.

Only "unreachable" skips, which the helper raises exclusively for a timeout or a
socket error. A bridge that answers and refuses still fails: authentication
rejected, a bad response, a catalog of the wrong shape. Those are what this
contract is for, and all seven paths were exercised against a stubbed helper to
confirm which fail and which do not.

129 contracts pass, with none of them red for a reason nobody intends to fix --
which was the point. A suite expected to be red stops being read.

Claude-Session: https://claude.ai/code/session_01Q84axqUE5inJhf5Jz9CFy1
---
 .../quickshell/home-assistant-helper-contract | 35 ++++++++++++++++---
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/tests/quickshell/home-assistant-helper-contract b/tests/quickshell/home-assistant-helper-contract
index 90d6c1e..641c363 100755
--- a/tests/quickshell/home-assistant-helper-contract
+++ b/tests/quickshell/home-assistant-helper-contract
@@ -12,21 +12,48 @@ helper="$project_root/config/dot/quickshell/scripts/panama-home-assistant"
 
 [[ -x "$helper" ]] || fail 'helper is missing or not executable'
 
-catalog="$($helper catalog)"
+# The helper exits 2 for any catalog it could not complete -- including both
+# cases below, which are not defects. Taking the status deliberately rather than
+# letting `set -e` act on it is what makes those skips reachable at all: they
+# were not. On a machine with no token, or with the server simply switched off,
+# this line aborted the script before either could run, and the contract failed
+# with no output whatsoever -- which reads as a crash rather than as a skip.
+catalog=""
+catalog_status=0
+catalog="$("$helper" catalog 2>/dev/null)" || catalog_status=$?
+
+[[ -n "$catalog" ]] || fail "the helper produced no output (exit $catalog_status)"
+jq -e . >/dev/null 2>&1 <<<"$catalog" || fail 'the helper did not answer with JSON'
+
+reason="$(jq -r '.error // "unknown"' <<<"$catalog")"
 
 # This asserts a LIVE, authenticated Home Assistant. An absent credential is not
 # a defect in Panama, so it skips rather than fails -- otherwise the suite is red
 # on any machine that has not been given a token, and a red suite that is
 # expected to be red stops being read.
-#
-# A configured-but-broken bridge still fails, which is the case worth catching.
 if [[ "$(jq -r '.configured' <<<"$catalog")" != "true" ]]; then
     printf 'Home Assistant helper contract: SKIP (no token configured)\n'
     printf '  Set PANAMA_HOME_ASSISTANT_TOKEN in config/bash/env to exercise this.\n'
-    printf '  Reason reported by the helper: %s\n' "$(jq -r '.error // "unknown"' <<<"$catalog")"
+    printf '  Reason reported by the helper: %s\n' "$reason"
     exit 0
 fi
 
+# Configured, but nothing answered: off the network, the VPN down, or the server
+# itself asleep. Also not a defect in Panama, and the same reasoning as the
+# extras contract skipping when dnf or Flathub cannot be reached.
+#
+# Only "unreachable", which the helper raises exclusively for a timeout or a
+# socket error. A bridge that ANSWERS and refuses -- authentication-required,
+# request-failed, invalid-response -- is a configured-but-broken bridge, which
+# is exactly the case worth catching, so those still fail.
+if [[ "$reason" == "unreachable" ]]; then
+    printf 'Home Assistant helper contract: SKIP (configured, but the bridge did not answer)\n'
+    printf '  Nothing to assert about a server that is not there.\n'
+    exit 0
+fi
+
+(( catalog_status == 0 )) || fail "the helper reported: $reason"
+
 jq -e '
   .ok == true and .configured == true and .error == "" and
   (.entities | type == "array" and length > 0) and