mode tool: read and set the desktop modes

dnd, presentation, nolock and quiet through statusctl. The output is
read back after a set, so a set that did not land is not reported as
done, and a running game's hold on presentation is named. test-mode.sh
checks it against a scratch runtime dir.

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

1 files changed, 48 insertions, 0 deletions

diff --git a/examples/tools/mode.sh b/examples/tools/mode.sh
new file mode 100755
index 0000000..d35ca8f
--- /dev/null
+++ b/examples/tools/mode.sh
@@ -0,0 +1,48 @@
+#!/bin/bash
+# desktop-assistant tool: read or set a desktop mode.
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License version 2 as published
+# by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+# Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# mode.sh <mode> [0|1]: the desktop modes in the status registry
+# (statusctl, quickshell repo). Empty second argument only reads. Check:
+# test-mode.sh.
+
+set -uo pipefail
+
+mode=${1:-}
+on=${2:-}
+
+case "$on" in
+    "") ;;
+    0|1) statusctl "$mode" set "$on" || exit 1 ;;
+    *) echo "on must be 1, 0 or empty, not: $on" >&2; exit 1 ;;
+esac
+
+# Read back rather than echo the request: a set that did not land must not
+# be reported as done. An unknown mode fails here, in statusctl.
+v=$(statusctl "$mode" get) || exit 1
+[ "$v" = 1 ] && s=on || s=off
+
+# statusctl get reads only the manual half of presentation; a running game
+# holds it on regardless (see statusctl's gaming_on).
+# Guarded on existence: 2>/dev/null cannot silence a failed input redirect.
+gf="${XDG_RUNTIME_DIR:-/tmp}/status.gaming"
+g=""
+[ -e "$gf" ] && g=$(tr -d '[:space:]' < "$gf" 2>/dev/null)
+if [ "$mode" = presentation ] && [ "$g" = 1 ]; then
+    echo "presentation: on (held on by a running game; manual setting $s)"
+else
+    echo "$mode: $s"
+fi