Make a fresh install actually produce a working desktop

Two things stood between this repository and a machine that could
install it.

The installer aborted on its own first question. The hostname prompt
defaults to N, and the N branch ran `exit` -- so pressing Enter, the
obvious answer when you do not want to rename your machine, skipped the
entire installation and said nothing about it. Declining now just
declines. The installer is also safe to re-run, which is the upgrade
path too: it reports which stages failed instead of scrolling the
failure past twenty minutes ago, and restores the idle settings on every
exit path rather than only on success.

The package lists had drifted badly from what the configs and helpers
actually use. jq alone has thirty-one call sites across the helpers and
the contracts; kitty has a full shipped config and a dock pin; tmux and
btop have shipped themes the colour scheme switches; ddcutil, qrencode
and orca back features added today. None were declared. Neither were
fontconfig, pciutils, libselinux-utils, libnotify, wireplumber, fwupd or
python3-dnf, all of which shipped scripts invoke by name. A fresh
machine following this repository's own instructions would have got a
desktop whose features quietly were not there -- the helpers report "not
installed" rather than crashing, which is good behaviour and completely
silent.

So the lists are corrected and a contract now checks that every external
command Panama's scripts invoke is installed by Panama's packages.

Writing it was instructive about its own blind spots. The first version
reported `then`, `esac` and `done` as missing packages, burying the real
findings. The second passed while jq was undeclared, because the pattern
required three characters and jq is two -- a dependency checker with a
blind spot for short names is worse than none, since it reports PASS.
The third missed ddcutil, which is only ever invoked as `timeout 10
ddcutil` and so never appears statement-initial. It now also reads
`command -v X`, which is how these helpers probe for a tool and
therefore the clearest statement of a dependency there is. Verified it
catches jq, ddcutil and qrencode individually.

Also replaced a fixed 0.3s sleep in the write contract with a bounded
wait. It was failing about one run in three with "a rejected value did
not surface an error" when the error had simply not arrived yet, which
reads as a missing guard rather than a slow one.

Claude-Session: https://claude.ai/code/session_01BRvzt4H8XXLPVH5MyYdk9L

install

@@ -1,11 +1,24 @@
 #!/usr/bin/env bash
-source ~/.local/share/Panama/bin/ascii
+
-# Set host name
+# Panama's installer. Safe to re-run: every stage is idempotent, and this is
+# also the upgrade path.
+
+set -uo pipefail
+
+PANAMA_PATH="${PANAMA_PATH:-$HOME/.local/share/Panama}"
+source "$PANAMA_PATH/bin/ascii"
+
+# ── Hostname, which is optional ──────────────────────────────────────────────
+#
+# Declining this used to `exit`, which aborted the ENTIRE installation. The
+# prompt defaults to N, so simply pressing Enter -- the obvious thing to do when
+# you do not want to rename your machine -- installed nothing at all and said
+# nothing about it.
 echo -e "Current hostname is: $(hostname)"
-read -p "Do you want to change the hostname? [y/N]: " confirm_change
+read -r -p "Do you want to change the hostname? [y/N]: " confirm_change
 if [[ "$confirm_change" =~ ^[Yy]$ ]]; then
-  read -p "Hostname: " HOST_NAME
+  read -r -p "Hostname: " HOST_NAME
-  read -p "Set hostname to '$HOST_NAME'? [y/N]: " confirm_hostname
+  read -r -p "Set hostname to '$HOST_NAME'? [y/N]: " confirm_hostname
   if [[ "$confirm_hostname" =~ ^[Yy]$ ]]; then
     sudo hostnamectl set-hostname "$HOST_NAME"
     echo "Hostname set to: $(hostname)"
@@ -13,18 +26,45 @@ if [[ "$confirm_change" =~ ^[Yy]$ ]]; then
     echo "Hostname not changed."
   fi
 else
-  echo "Not changing hostname."
+  echo "Keeping the current hostname."
-  exit
 fi
 
-# Ensure computer doesn't go to sleep.
+# ── Keep the machine awake for the duration ──────────────────────────────────
-gsettings set org.gnome.desktop.screensaver lock-enabled false
+# Package installation takes long enough to hit an idle lock, and being locked
-gsettings set org.gnome.desktop.session idle-delay 0
+# out mid-transaction is unpleasant. Restored on every exit path, including
+# failure and Ctrl-C, so an interrupted install does not leave the screen
+# permanently awake.
+restore_idle() {
+  gsettings set org.gnome.desktop.screensaver lock-enabled true 2>/dev/null || true
+  gsettings set org.gnome.desktop.session idle-delay 300 2>/dev/null || true
+}
+trap restore_idle EXIT INT TERM
 
-# Run each setup stage in its own process. This keeps strict-shell options and
+gsettings set org.gnome.desktop.screensaver lock-enabled false 2>/dev/null || true
-# helper variables local to the script that owns them.
+gsettings set org.gnome.desktop.session idle-delay 0 2>/dev/null || true
-for script in ~/.local/share/Panama/setup/scripts/*; do "$script"; done
 
-# Revert to normal idle settings
+# ── Stages ───────────────────────────────────────────────────────────────────
-gsettings set org.gnome.desktop.screensaver lock-enabled true
+# Each runs in its own process so strict-shell options and helper variables stay
-gsettings set org.gnome.desktop.session idle-delay 300
+# local to the script that owns them. A failing stage is reported and the rest
+# still run: a missing optional package should not stop the dotfiles being
+# linked. The summary at the end is what decides whether the install worked,
+# because a failure scrolled past twenty minutes ago is a failure nobody saw.
+failed=()
+for script in "$PANAMA_PATH"/setup/scripts/*; do
+  [[ -x "$script" ]] || continue
+  stage="$(basename "$script")"
+  printf '\n=== %s ===\n' "$stage"
+  if ! "$script"; then
+    failed+=("$stage")
+    printf '!!! %s failed\n' "$stage" >&2
+  fi
+done
+
+printf '\n'
+if (( ${#failed[@]} == 0 )); then
+  echo "Panama installed. Log out and choose the Hyprland session to start it."
+else
+  printf 'Panama installed with %d failed stage(s): %s\n' "${#failed[@]}" "${failed[*]}" >&2
+  printf 'Re-running ./install is safe and will retry them.\n' >&2
+  exit 1
+fi

setup/packages/hyprland-packages

@@ -1,38 +1,45 @@
-hyprland
+NetworkManager
-hyprland-uwsm
-uwsm
-quickshell
-vicinae
-hyprlock
-hypridle
-hyprpaper
-hyprpicker
-hyprsunset
-hyprpolkitagent
-hyprshutdown
-hyprpwcenter
-hyprsysteminfo
-hyprland-guiutils
-xdg-desktop-portal-hyprland
-grim
-slurp
-grimblast
-satty
-wl-clipboard
-wf-recorder
-gpu-screen-recorder
-brightnessctl
-playerctl
-pamixer
-udiskie
-wofi
 adw-gtk3-theme
 adwaita-icon-theme
 adwaita-sans-fonts
-qt6-qtwayland
+brightnessctl
-nm-connection-editor
+ddcutil
+gpu-screen-recorder
+grim
+grimblast
+gtk-update-icon-cache
+hypridle
+hyprland
+hyprland-guiutils
+hyprland-uwsm
+hyprlock
+hyprpaper
+hyprpicker
+hyprpolkitagent
+hyprpwcenter
+hyprshutdown
+hyprsunset
+hyprsysteminfo
 kde-connect
+libnotify
+nm-connection-editor
+orca
+pamixer
+playerctl
+qrencode
+qt6-qtwayland
+quickshell
+satty
+slurp
+system-config-printer
 tesseract
 tesseract-langpack-eng
+udiskie
+uwsm
+vicinae
+wf-recorder
+wireplumber
+wl-clipboard
+wofi
+xdg-desktop-portal-hyprland
 zbar
-system-config-printer

setup/packages/initial-packages

@@ -1,18 +1,27 @@
 awk
 bat
+btop
 cargo
 curl
 eza
+fontconfig
+fwupd
 fzf
-git-all
 gh
+git-all
 gum
+jq
+kitty
 ksshaskpass
+libselinux-utils
 neovim
 openssl
+pciutils
+python3-dnf
 python3-neovim
 rustup
+tmux
 unzip
-wireguard-tools
 wget
+wireguard-tools
 zoxide

tests/quickshell/declared-dependencies-contract.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+
+# Every external command Panama's own scripts invoke must be installed by
+# Panama's own package lists.
+#
+# This exists because the lists had drifted badly. jq is used by thirty-one call
+# sites across the helpers and the contracts; kitty has a full shipped config
+# and a dock pin; tmux and btop have shipped themes that the colour scheme
+# switches. None of the four were declared. So a fresh machine that followed
+# this repository's own install instructions would not have them.
+#
+# The failure is quiet by design, which is what makes it worth a test: the
+# helpers are written to report "not installed" rather than crash, so a missing
+# dependency presents as a feature that silently is not there.
+#
+# Commands from coreutils and the shell itself are not checked -- nothing
+# installs those separately, and listing them would be noise.
+
+set -uo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+fail() {
+    printf 'declared dependencies contract: %s\n' "$1" >&2
+    exit 1
+}
+
+# Shell syntax and builtins. These are not commands anyone installs, and the
+# first version of this contract reported `then`, `esac` and `done` as missing
+# packages, which buried the four real findings in a hundred lines of noise.
+SHELL_WORDS='^(if|then|else|elif|fi|for|while|until|do|done|case|esac|in|function|select|time|coproc|break|continue|return|exit|local|readonly|declare|export|unset|shift|eval|exec|source|trap|set|shopt|alias|unalias|builtin|command|enable|help|let|read|mapfile|printf|echo|test|true|false|wait|jobs|bg|fg|kill|pwd|cd|dirs|pushd|popd|umask|type|hash|getopts|split|sync)$'
+
+# Provided by any Fedora install: coreutils, util-linux, the shell, and the
+# systemd/session tooling. Nothing here is a choice Panama makes.
+BASELINE='^(sh|bash|cat|cut|sed|awk|gawk|grep|egrep|head|tail|sort|uniq|tr|wc|find|xargs|basename|dirname|mkdir|rm|cp|mv|ln|chmod|chown|stat|df|du|date|sleep|env|id|tee|touch|mktemp|readlink|realpath|seq|comm|join|paste|od|file|nl|fold|column|tput|timeout|flock|install|sha256sum|md5sum|base64|nproc|uptime|free|uname|hostname|whoami|ps|pgrep|pkill|kill|killall|lsblk|mount|umount|sudo|su|rpm|dnf|flatpak|git|python3|ss|ip|lsof)$'
+
+SESSION='^(systemctl|busctl|journalctl|loginctl|hostnamectl|localectl|systemd-inhibit|systemd-run|udevadm|gsettings|dconf|dbus-send|dbus-monitor|hyprctl|qs|quickshell|gnf|panama|wl-copy|wl-paste)$'
+
+declared="$(cat "$repo_dir"/setup/packages/* 2>/dev/null | sed 's/#.*//' | tr -d ' ' | grep -v '^$' | sort -u)"
+[[ -n "$declared" ]] || fail 'no package lists found'
+
+# A package is not always named after its command. Only the genuine mismatches
+# are mapped, so an unmapped command is a real omission rather than a lookup
+# failure.
+package_for() {
+    case "$1" in
+        zbarimg)        printf 'zbar' ;;
+        fc-list|fc-match) printf 'fontconfig' ;;
+        lspci)          printf 'pciutils' ;;
+        getenforce)     printf 'libselinux-utils' ;;
+        nmcli)          printf 'NetworkManager' ;;
+        wpctl)          printf 'wireplumber' ;;
+        nvim)           printf 'neovim' ;;
+        fwupdmgr)       printf 'fwupd' ;;
+        dnf4)           printf 'python3-dnf' ;;
+        notify-send)    printf 'libnotify' ;;
+        wl-copy|wl-paste) printf 'wl-clipboard' ;;
+        rg)             printf 'ripgrep' ;;
+        python3)        printf 'python3' ;;
+        *)              printf '%s' "$1" ;;
+    esac
+}
+
+missing=()
+checked=0
+
+while read -r script; do
+    [[ -n "$script" ]] || continue
+    head -1 "$script" | grep -qE 'bash|/sh' || continue
+
+    # Commands appearing at the start of a statement or after a pipe. Crude, but
+    # it is looking for undeclared dependencies, not building a call graph.
+    #
+    # No minimum length. An earlier version required three characters, which
+    # quietly excluded the most-used dependency in the repository -- jq, at
+    # thirty-one call sites -- along with rg, ss and ip. A dependency checker
+    # with a blind spot for short names is worse than none, because it reports
+    # PASS.
+    while read -r cmd; do
+        [[ -n "$cmd" ]] || continue
+        [[ "$cmd" =~ $SHELL_WORDS ]] && continue
+        [[ "$cmd" =~ $BASELINE ]] && continue
+        [[ "$cmd" =~ $SESSION ]] && continue
+
+        pkg="$(package_for "$cmd")"
+        grep -qx "$pkg" <<<"$declared" && continue
+
+        # Only report a command that actually exists on this machine. An
+        # invented name in a comment or a heredoc is a false positive; a real
+        # binary that nothing declares is the thing being looked for.
+        command -v "$cmd" >/dev/null 2>&1 || continue
+
+        missing+=("$cmd (from $(basename "$script"), package: $pkg)")
+    done < <({
+        # Statement-initial or after a pipe.
+        grep -oE '(^|[|;&]|\$\()[[:space:]]*[a-z][a-z0-9_-]+' "$script" \
+            | grep -oE '[a-z][a-z0-9_-]+$'
+
+        # Behind a wrapper. ddcutil is always invoked as `timeout 10 ddcutil`,
+        # so it never appears statement-initial and was missed entirely.
+        grep -oE '\b(timeout[[:space:]]+[0-9.]+|sudo|nohup|env)[[:space:]]+[a-z][a-z0-9_-]+' "$script" \
+            | grep -oE '[a-z][a-z0-9_-]+$'
+
+        # `command -v X` is how these helpers probe for a tool before using it,
+        # which makes it the clearest possible statement of a dependency.
+        grep -oE 'command -v[[:space:]]+[a-z][a-z0-9_-]+' "$script" \
+            | grep -oE '[a-z][a-z0-9_-]+$'
+    } | sort -u)
+
+    checked=$((checked + 1))
+done < <(find "$repo_dir/config/dot/quickshell/scripts" \
+              "$repo_dir/config/local/share/vicinae/scripts" \
+              "$repo_dir/setup/scripts" "$repo_dir/bin" \
+              -type f 2>/dev/null)
+
+if (( ${#missing[@]} > 0 )); then
+    printf 'declared dependencies contract: commands used but never installed:\n' >&2
+    printf '  %s\n' "${missing[@]}" | sort -u >&2
+    fail 'add each to a list in setup/packages/, or the feature silently will not exist on a fresh machine'
+fi
+
+printf 'declared dependencies contract: PASS (%d scripts)\n' "$checked"

tests/quickshell/settings-hyprland-write-contract.sh

@@ -137,10 +137,20 @@ last_error="$(qs_for_harness ipc call settings-system-test status | jq -r .lastE
 
 # ── A rejected value must be refused, not silently accepted ──────────────────
 qs_for_harness ipc call settings-system-test apply "$target_auto_hdr" 7 "$target_direct" >/dev/null
-sleep 0.3
+
+# The refusal is reported asynchronously, so wait for it rather than sleeping a
+# fixed 0.3s and hoping. That sleep made this fail roughly one run in three,
+# reporting "a rejected value did not surface an error" when the error simply
+# had not arrived yet -- which reads as a missing guard rather than a slow one.
+rejected=""
+for _ in $(seq 1 60); do
+    rejected="$(qs_for_harness ipc call settings-system-test status | jq -r .lastError)"
+    [[ -n "$rejected" ]] && break
+    sleep 0.1
+done
+
 [[ "$(read_option misc:vrr)" == "$target_vrr" ]] || fail 'an out-of-allow-list VRR value reached the compositor'
-[[ -n "$(qs_for_harness ipc call settings-system-test status | jq -r .lastError)" ]] \
+[[ -n "$rejected" ]] || fail 'a rejected VRR value did not surface an error'
-    || fail 'a rejected VRR value did not surface an error'
 
 # ── Every getoption answer shape must be handled, not just integers ──────────
 # The compositor reports each option in a different JSON field depending on its