Files
Panama/tests/quickshell/panama-doctor-contract.sh
T

432 lines
19 KiB
Bash
Executable File

#!/usr/bin/env bash
# The doctor is deliberately exercised through its command boundary. The
# fixture commands include sensitive-looking output so this test proves the
# report only retains explicitly parsed, non-sensitive observations.
set -euo pipefail
repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
doctor="$repo_dir/config/dot/quickshell/scripts/panama-doctor"
fixture_root="$repo_dir/tests/quickshell/fixtures/doctor"
fail() {
printf 'panama doctor contract: %s\n' "$1" >&2
exit 1
}
fixture="$(mktemp -d /tmp/panama-doctor.XXXXXX)"
trap 'rm -rf "$fixture"' EXIT
home="$fixture/home"
config_home="$home/.config"
state_home="$home/.local/state"
runtime_dir="$fixture/runtime"
bin_dir="$fixture/bin"
data_home="$home/.local/share"
mkdir -p "$config_home" "$state_home" "$runtime_dir" "$bin_dir" "$data_home/vicinae"
cp "$fixture_root/bin/"* "$bin_dir/"
chmod +x "$bin_dir"/*
# These are intentionally tiny stand-ins for authored executable probes. The
# named fixture scripts above cover probes whose output needs branch coverage.
for tool in hyprctl wl-paste grim tesseract kitty nextcloud rustdesk kdeconnect-cli; do
cat >"$bin_dir/$tool" <<'EOF'
#!/usr/bin/bash
case "${0##*/}" in
hyprctl) printf 'Hyprland 0.50.0\n' ;;
esac
EOF
chmod +x "$bin_dir/$tool"
done
cat >"$bin_dir/flatpak" <<'EOF'
#!/usr/bin/bash
if [[ "${1:-}" == "info" && "${2:-}" == "app.bluebubbles.BlueBubbles" \
&& "${PANAMA_DOCTOR_FIXTURE_BLUEBUBBLES:-installed}" == "installed" ]]; then
printf 'BlueBubbles fixture-secret-token\n'
exit 0
fi
exit 1
EOF
chmod +x "$bin_dir/flatpak"
cat >"$bin_dir/calendar-agenda" <<'EOF'
#!/usr/bin/bash
if [[ "${1:-}" != "probe" ]]; then
exit 2
fi
case "${PANAMA_DOCTOR_FIXTURE_CALENDAR:-ready}" in
ready) printf '{"eds":true,"sourceRegistry":true,"enabledSources":2,"event":"fixture clipboard body"}\n' ;;
malformed) printf 'calendar AA:BB:CC:DD:EE:FF\n' ;;
timeout) /usr/bin/sleep 2; printf '{"enabledSources":2}\n' ;;
*) printf '{"eds":true,"sourceRegistry":true,"enabledSources":0}\n' ;;
esac
EOF
chmod +x "$bin_dir/calendar-agenda"
cat >"$bin_dir/panama-brightness" <<'EOF'
#!/usr/bin/bash
case "${PANAMA_DOCTOR_FIXTURE_BRIGHTNESS:-ready}" in
ready) printf '{"displays":[{"connector":"AA:BB:CC:DD:EE:FF"}],"error":""}\n' ;;
denied) printf '{"displays":[],"error":"fixture-secret-token"}\n' ;;
malformed) printf 'fixture clipboard body\n' ;;
esac
EOF
chmod +x "$bin_dir/panama-brightness"
mkdir -p "$config_home/autostart"
touch "$config_home/autostart/nextcloud.desktop"
for name in hypr quickshell uwsm vicinae; do
ln -s "$repo_dir/config/dot/$name" "$config_home/$name"
done
ln -s "$repo_dir/config/local/share/vicinae/scripts" "$data_home/vicinae/scripts"
run_doctor() {
HOME="$home" \
PATH="$bin_dir" \
XDG_CURRENT_DESKTOP=Hyprland \
PANAMA_HOME_ASSISTANT_URL='https://fixture.invalid' \
PANAMA_HOME_ASSISTANT_TOKEN='fixture-secret-token' \
PANAMA_DOCTOR_ROOT="$repo_dir" \
PANAMA_DOCTOR_HOME="$home" \
PANAMA_DOCTOR_CONFIG_HOME="$config_home" \
PANAMA_DOCTOR_STATE_HOME="$state_home" \
PANAMA_DOCTOR_RUNTIME_DIR="$runtime_dir" \
PANAMA_DOCTOR_PATH="$bin_dir" \
PANAMA_DOCTOR_TIMEOUT="${PANAMA_DOCTOR_TIMEOUT:-0.2}" \
/usr/bin/python3 "$doctor" "$@"
}
expected_order=$'desktop.hyprland\ndesktop.quickshell\ndesktop.notifications\ndesktop.portals\ndesktop.hyprpaper\ndesktop.hypridle\ndesktop.vicinae\ninput.pipewire\ninput.clipboard\ninput.wallpaper\ninput.capture\ninput.ocr\ninput.brightness\nintegration.nextcloud\nintegration.rustdesk\nintegration.kdeconnect\nintegration.bluebubbles\nintegration.home-assistant\nintegration.calendar\npanama.runtime-links\npanama.vicinae-commands\npanama.selected-terminal\npanama.selected-launcher\npanama.processes\npanama.caffeine'
assert_schema_and_redaction() {
local snapshot="$1"
jq -e '.schemaVersion == 1
and (.generatedAt | type == "string")
and (.summary.status | IN("healthy", "warning", "error"))
and (.context.session | IN("hyprland", "other"))
and (.context.versions | type == "array")
and ([.checks[].id] | length == 25)
and ([.checks[].id] | unique | length == 25)
and ([.checks[].status] | all(IN("ok", "warning", "error", "unconfigured")))' \
>/dev/null <<<"$snapshot" || fail "invalid schema: $snapshot"
[[ "$(jq -r '.checks[].id' <<<"$snapshot")" == "$expected_order" ]] \
|| fail "checks are not in the authored order"
! grep -Fq 'fixture-secret-token' <<<"$snapshot" \
|| fail 'report exposed a fixture secret'
! grep -Fq 'fixture clipboard body' <<<"$snapshot" \
|| fail 'report exposed clipboard or calendar content'
! grep -Fq 'AA:BB:CC:DD:EE:FF' <<<"$snapshot" \
|| fail 'report exposed a device address'
}
check_status() {
local snapshot="$1" id="$2" expected="$3"
[[ "$(jq -r --arg id "$id" '.checks[] | select(.id == $id) | .status' <<<"$snapshot")" == "$expected" ]] \
|| fail "$id did not report $expected: $snapshot"
}
snapshot="$(run_doctor --json)"
assert_schema_and_redaction "$snapshot"
# A healthy systemd-backed service stays healthy.
check_status "$snapshot" desktop.hyprpaper ok
# Arbitrary parent environment values are not propagated into probes.
sealed_environment="$(PANAMA_DOCTOR_FIXTURE_PROBE_SECRET=fixture-secret-token run_doctor --json)"
assert_schema_and_redaction "$sealed_environment"
check_status "$sealed_environment" desktop.hyprpaper ok
# An OS-level launch failure is contained as a check result, never a failed
# doctor invocation or a partial snapshot.
chmod 0644 "$bin_dir/systemctl"
if ! launch_failure="$(run_doctor --json)"; then
chmod +x "$bin_dir/systemctl"
fail 'launch failure prevented the doctor from emitting JSON'
fi
chmod +x "$bin_dir/systemctl"
assert_schema_and_redaction "$launch_failure"
check_status "$launch_failure" desktop.hyprpaper error
# A missing required executable is an error rather than a crash.
mv "$bin_dir/qs" "$bin_dir/qs.off"
missing_qs="$(run_doctor --json)"
check_status "$missing_qs" desktop.quickshell error
mv "$bin_dir/qs.off" "$bin_dir/qs"
# Optional integrations stay neutral until the user configures them.
rm "$config_home/autostart/nextcloud.desktop"
unconfigured_nextcloud="$(run_doctor --json)"
check_status "$unconfigured_nextcloud" integration.nextcloud unconfigured
touch "$config_home/autostart/nextcloud.desktop"
# A configured integration that stopped is actionable with an authored label,
# never an application name or command derived from probe output.
stopped_nextcloud="$(PANAMA_DOCTOR_FIXTURE_STOPPED=nextcloud.service run_doctor --json)"
check_status "$stopped_nextcloud" integration.nextcloud warning
jq -e '.checks[] | select(.id == "integration.nextcloud")
| .action == {kind:"open", label:"Open Nextcloud", confirm:false}' \
>/dev/null <<<"$stopped_nextcloud" || fail 'Nextcloud action was not authored'
# DDC errors are classified without retaining connectors or bus addresses.
denied_brightness="$(PANAMA_DOCTOR_FIXTURE_BRIGHTNESS=denied run_doctor --json)"
check_status "$denied_brightness" input.brightness warning
jq -e '.checks[] | select(.id == "input.brightness")
| .action == {kind:"instructions", label:"View setup instructions", confirm:false, target:"ddc-permissions"}' \
>/dev/null <<<"$denied_brightness" || fail 'DDC instructions were not authored'
# A bounded probe timeout becomes a result, never a helper failure.
timed_calendar="$(PANAMA_DOCTOR_FIXTURE_CALENDAR=timeout PANAMA_DOCTOR_TIMEOUT=0.05 run_doctor --json)"
check_status "$timed_calendar" integration.calendar warning
jq -e '.checks[] | select(.id == "integration.calendar")
| .action == {kind:"open", label:"Open Date & Time", confirm:false, target:"datetime"}' \
>/dev/null <<<"$timed_calendar" || fail 'calendar action was not authored'
# Exact Panama/Caffeine inhibitor rows detect duplicates without exposing PIDs.
duplicated_caffeine="$(PANAMA_DOCTOR_FIXTURE_CAFFEINE=duplicate run_doctor --json)"
check_status "$duplicated_caffeine" panama.caffeine warning
jq -e '.checks[] | select(.id == "panama.caffeine")
| .action == {kind:"repair", label:"Release duplicate inhibitors", confirm:false}' \
>/dev/null <<<"$duplicated_caffeine" || fail 'Caffeine repair action was not authored'
! jq -r '.checks[] | select(.id == "panama.caffeine") | .detail' <<<"$duplicated_caffeine" | grep -Eq '[0-9]{3,}' \
|| fail 'Caffeine detail exposed inhibitor PIDs'
# Process counts use only exact authored names and never expose command lines or PIDs.
duplicated_processes="$(PANAMA_DOCTOR_FIXTURE_PROCESSES=quickshell:duplicate run_doctor --json)"
check_status "$duplicated_processes" panama.processes warning
! jq -r '.checks[] | select(.id == "panama.processes") | .detail' <<<"$duplicated_processes" | grep -Eq '[0-9]{3,}' \
|| fail 'process detail exposed a PID'
# Invalid output for a non-Quickshell authored process is not a normal zero
# count that can be hidden by the running Quickshell process.
malformed_processes="$(PANAMA_DOCTOR_FIXTURE_PROCESSES=hyprpaper:malformed run_doctor --json)"
check_status "$malformed_processes" panama.processes warning
# Panama/Caffeine-shaped rows that do not satisfy the fixed inhibitor schema
# are unavailable rather than reported as a healthy no-inhibitor state.
malformed_caffeine="$(PANAMA_DOCTOR_FIXTURE_CAFFEINE=malformed run_doctor --json)"
check_status "$malformed_caffeine" panama.caffeine warning
# A decoding error raised inside a concurrent probe is converted to a complete
# snapshot rather than escaping from Future.result().
if ! invalid_probe="$(PANAMA_DOCTOR_FIXTURE_BUS=invalid-utf8 run_doctor --json)"; then
fail 'unexpected probe exception prevented the doctor from emitting JSON'
fi
assert_schema_and_redaction "$invalid_probe"
check_status "$invalid_probe" desktop.portals warning
# Configured Home Assistant failures route to the exact authored Settings page.
rm "$config_home/quickshell"
mkdir -p "$config_home/quickshell/scripts"
home_assistant_failure="$(run_doctor --json)"
check_status "$home_assistant_failure" integration.home-assistant warning
jq -e '.checks[] | select(.id == "integration.home-assistant")
| .action == {kind:"open", label:"Open Home settings", confirm:false, target:"home-phone"}' \
>/dev/null <<<"$home_assistant_failure" || fail 'Home Assistant action was not routed to home-phone'
# Invalid probe text is contained in its own check and never copied to JSON.
malformed_calendar="$(PANAMA_DOCTOR_FIXTURE_CALENDAR=malformed run_doctor --json)"
check_status "$malformed_calendar" integration.calendar warning
assert_schema_and_redaction "$malformed_calendar"
summary="$(run_doctor --summary)"
[[ "$summary" =~ ^Panama\ system\ health:\ (healthy|warning|error)\ \([0-9]+\ ok,\ [0-9]+\ warnings,\ [0-9]+\ errors,\ [0-9]+\ unconfigured\)$ ]] \
|| fail "summary is not concise: $summary"
# Repairs run against a second, disposable Panama root. Every process boundary
# records its argv, and every filesystem assertion is confined to this fixture.
repair_root="$fixture/repair-root"
repair_log="$runtime_dir/repair.log"
mkdir -p "$repair_root/config/dot" "$repair_root/setup/scripts"
for name in hypr quickshell uwsm vicinae; do
mkdir -p "$repair_root/config/dot/$name"
done
mv "$bin_dir/systemctl" "$bin_dir/systemctl-probe"
cat >"$bin_dir/systemctl" <<'EOF'
#!/usr/bin/bash
set -euo pipefail
if [[ "${1:-}" == "--user" && "${2:-}" == "restart" ]]; then
printf 'systemctl' >>"$XDG_RUNTIME_DIR/repair.log"
printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
[[ ! -e "$XDG_RUNTIME_DIR/fail-repair" ]] || exit 5
exit 0
fi
exec "${0%/*}/systemctl-probe" "$@"
EOF
cat >"$bin_dir/panama-action" <<'EOF'
#!/usr/bin/bash
set -euo pipefail
printf 'panama-action' >>"$XDG_RUNTIME_DIR/repair.log"
printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
EOF
cat >"$bin_dir/kill" <<'EOF'
#!/usr/bin/bash
set -euo pipefail
printf 'kill' >>"$XDG_RUNTIME_DIR/repair.log"
printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
EOF
cat >"$bin_dir/systemd-inhibit" <<'EOF'
#!/usr/bin/bash
set -euo pipefail
printf 'systemd-inhibit' >>"$XDG_RUNTIME_DIR/repair.log"
printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
uid="$(/usr/bin/id -u)"
printf 'Panama %s fixture-user 4101 systemd-inhibit sleep:idle Caffeine block\n' "$uid"
printf 'Panama %s fixture-user 4102 systemd-inhibit sleep:idle Caffeine block\n' "$uid"
printf 'Other %s fixture-user 4999 systemd-inhibit sleep:idle Caffeine block\n' "$uid"
printf 'Panama 99999 fixture-user 4998 systemd-inhibit sleep:idle Caffeine block\n'
printf 'Panama %s fixture-user 4997 systemd-inhibit sleep:idle Other block\n' "$uid"
printf 'Panama %s fixture-user 4996 systemd-inhibit sleep:idle Caffeine delay\n' "$uid"
EOF
cat >"$repair_root/setup/scripts/link-vicinae-scripts" <<'EOF'
#!/usr/bin/bash
set -euo pipefail
printf 'link-vicinae-scripts|%s' "$0" >>"$XDG_RUNTIME_DIR/repair.log"
if (( $# > 0 )); then
printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
fi
printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
EOF
chmod +x "$bin_dir/systemctl" "$bin_dir/panama-action" "$bin_dir/kill" \
"$bin_dir/systemd-inhibit" "$repair_root/setup/scripts/link-vicinae-scripts"
run_repair() {
HOME="$home" \
PATH="$bin_dir" \
XDG_CURRENT_DESKTOP=Hyprland \
PANAMA_DOCTOR_ROOT="$repair_root" \
PANAMA_DOCTOR_HOME="$home" \
PANAMA_DOCTOR_CONFIG_HOME="$config_home" \
PANAMA_DOCTOR_STATE_HOME="$state_home" \
PANAMA_DOCTOR_RUNTIME_DIR="$runtime_dir" \
PANAMA_DOCTOR_PATH="$bin_dir" \
PANAMA_DOCTOR_TIMEOUT=0.2 \
/usr/bin/python3 "$doctor" "$@"
}
repair_output=""
repair_status=0
invoke_repair() {
set +e
repair_output="$(run_repair --repair "$1" --json)"
repair_status=$?
set -e
}
assert_repair_result() {
local id="$1" accepted="$2" exit_code="$3"
jq -e --arg id "$id" --argjson accepted "$accepted" --argjson exitCode "$exit_code" '
(keys | sort) == ["accepted", "checkId", "exitCode", "message", "schemaVersion"]
and .schemaVersion == 1
and .checkId == $id
and .accepted == $accepted
and .exitCode == $exitCode
and (.message | type == "string" and length > 0)
' >/dev/null <<<"$repair_output" || fail "invalid repair result for $id: $repair_output"
}
for repair_case in \
'desktop.hyprpaper|systemctl|--user|restart|hyprpaper.service' \
'desktop.hypridle|systemctl|--user|restart|hypridle.service' \
'desktop.vicinae|systemctl|--user|restart|vicinae.service' \
'desktop.quickshell|panama-action|restart-shell'; do
IFS='|' read -r repair_id executable arg1 arg2 arg3 <<<"$repair_case"
: >"$repair_log"
invoke_repair "$repair_id"
[[ "$repair_status" == 0 ]] || fail "$repair_id returned $repair_status"
assert_repair_result "$repair_id" true 0
expected="$executable|$arg1"
[[ -z "$arg2" ]] || expected+="|$arg2"
[[ -z "$arg3" ]] || expected+="|$arg3"
[[ "$(<"$repair_log")" == "$expected" ]] \
|| fail "$repair_id argv was not exact: $(<"$repair_log")"
done
# Known process failures still return complete JSON and preserve the command's
# exit status for the QML state machine.
touch "$runtime_dir/fail-repair"
: >"$repair_log"
invoke_repair desktop.vicinae
rm "$runtime_dir/fail-repair"
[[ "$repair_status" == 5 ]] || fail "failed repair returned $repair_status instead of 5"
assert_repair_result desktop.vicinae true 5
[[ "$(<"$repair_log")" == 'systemctl|--user|restart|vicinae.service' ]] \
|| fail 'failed repair changed the authored argv'
# The Vicinae repair executes only the authored setup helper with no arguments.
: >"$repair_log"
invoke_repair panama.vicinae-commands
[[ "$repair_status" == 0 ]] || fail "Vicinae command repair returned $repair_status"
assert_repair_result panama.vicinae-commands true 0
[[ "$(<"$repair_log")" == "link-vicinae-scripts|$repair_root/setup/scripts/link-vicinae-scripts" ]] \
|| fail "Vicinae command repair argv was not exact: $(<"$repair_log")"
# Runtime-link repair may replace only the four authored symlink names. Broken
# or absent links are recreated toward authored tracked destinations; regular
# files and directories remain untouched and make the result incomplete.
for name in hypr quickshell uwsm vicinae; do
path="$config_home/$name"
if [[ -e "$path" || -L "$path" ]]; then
mv "$path" "$fixture/pre-repair-$name"
fi
done
ln -s "$fixture/missing-hypr" "$config_home/hypr"
ln -s "$fixture/missing-quickshell" "$config_home/quickshell"
printf 'user-owned file\n' >"$config_home/uwsm"
mkdir "$config_home/vicinae"
ln -s "$fixture/untouched" "$config_home/not-panama"
: >"$repair_log"
invoke_repair panama.runtime-links
[[ "$repair_status" == 1 ]] || fail "blocked runtime-link repair returned $repair_status"
assert_repair_result panama.runtime-links true 1
[[ -L "$config_home/hypr" && "$(readlink "$config_home/hypr")" == "$repair_root/config/dot/hypr" ]] \
|| fail 'hypr link was not recreated toward its authored destination'
[[ -L "$config_home/quickshell" && "$(readlink "$config_home/quickshell")" == "$repair_root/config/dot/quickshell" ]] \
|| fail 'quickshell link was not recreated toward its authored destination'
[[ -f "$config_home/uwsm" && "$(<"$config_home/uwsm")" == 'user-owned file' ]] \
|| fail 'runtime-link repair replaced a regular file'
[[ -d "$config_home/vicinae" && ! -L "$config_home/vicinae" ]] \
|| fail 'runtime-link repair replaced a user-owned directory'
[[ -L "$config_home/not-panama" && "$(readlink "$config_home/not-panama")" == "$fixture/untouched" ]] \
|| fail 'runtime-link repair touched an unauthored link name'
[[ ! -s "$repair_log" ]] || fail 'runtime-link repair launched a process'
# Caffeine repair parses exact authored metadata, keeps the first valid lock,
# and releases only later exact matches.
: >"$repair_log"
invoke_repair panama.caffeine
[[ "$repair_status" == 0 ]] || fail "Caffeine repair returned $repair_status"
assert_repair_result panama.caffeine true 0
expected_caffeine=$'systemd-inhibit|--list|--no-pager|--no-legend\nkill|--|4102'
[[ "$(<"$repair_log")" == "$expected_caffeine" ]] \
|| fail "Caffeine repair did not preserve/filter exact inhibitors: $(<"$repair_log")"
# Rejected IDs are complete JSON, exit 2, and cause neither a process launch
# nor a filesystem mutation.
fixture_state() {
find "$config_home" -mindepth 1 -printf '%P|%y|%l\n' | sort | sha256sum | awk '{print $1}'
}
for rejected_id in unknown.check integration.home-assistant input.brightness \
desktop.notifications ../../escape 'desktop.vicinae;touch injected'; do
: >"$repair_log"
before_state="$(fixture_state)"
invoke_repair "$rejected_id"
[[ "$repair_status" == 2 ]] || fail "$rejected_id returned $repair_status instead of 2"
assert_repair_result "$rejected_id" false 2
[[ ! -s "$repair_log" ]] || fail "$rejected_id launched a process"
[[ "$(fixture_state)" == "$before_state" ]] || fail "$rejected_id mutated the filesystem"
done
printf 'panama doctor contract: PASS\n'