fix: receive Xfce configuration from dotfiles

The run-terminal program is not Qubes or Qusal specific and even could
be in the dotfiles, but Xfce helpers.rc depends on it to get any
available application.

For: https://github.com/ben-grande/dotfiles/pull/1

salt/browser/configure.sls

@@ -1,5 +1,5 @@
 {#
-SPDX-FileCopyrightText: 2023 - 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+SPDX-FileCopyrightText: 2023 - 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 #}
@@ -9,6 +9,6 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 include:
   - dotfiles.copy-sh
   - dotfiles.copy-x11
-  - dotfiles.copy-xfce
+  - utils.tools.xfce
 
 {% endif -%}

salt/browser/install-common.sls

@@ -1,5 +1,5 @@
 {#
-SPDX-FileCopyrightText: 2023 - 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+SPDX-FileCopyrightText: 2023 - 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 #}
@@ -8,6 +8,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 include:
   - utils.tools.common.update
+  - utils.tools.xfce
   - sys-usb.install-client-fido
   - sys-audio.install-client
 

salt/reader/configure.sls

@@ -1,5 +1,5 @@
 {#
-SPDX-FileCopyrightText: 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+SPDX-FileCopyrightText: 2024 - 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 #}
@@ -9,6 +9,6 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 include:
   - dotfiles.copy-sh
   - dotfiles.copy-x11
-  - dotfiles.copy-xfce
+  - utils.tools.xfce
 
 {% endif -%}

salt/reader/install.sls

@@ -1,6 +1,6 @@
 {#
 SPDX-FileCopyrightText: 2022 - 2023 unman <unman@thirdeyesecurity.org>
-SPDX-FileCopyrightText: 2023 - 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+SPDX-FileCopyrightText: 2023 - 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 #}
@@ -9,6 +9,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 include:
   - utils.tools.common.update
+  - utils.tools.xfce
 
 "{{ slsdotpath }}-installed":
   pkg.installed:

salt/signal/configure.sls

@@ -1,5 +1,5 @@
 {#
-SPDX-FileCopyrightText: 2023 - 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+SPDX-FileCopyrightText: 2023 - 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 #}
@@ -8,7 +8,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 include:
   - dotfiles.copy-x11
-  - dotfiles.copy-xfce
+  - utils.tools.xfce
 
 "{{ slsdotpath }}-desktop-autostart":
   file.symlink:

salt/signal/install.sls

@@ -1,5 +1,5 @@
 {#
-SPDX-FileCopyrightText: 2023 - 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+SPDX-FileCopyrightText: 2023 - 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 #}
@@ -9,6 +9,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 include:
   - .install-repo
   - utils.tools.common.update
+  - utils.tools.xfce
   - dotfiles.copy-x11
   - sys-audio.install-client
 

salt/sys-syncthing/configure.sls

@@ -1,9 +1,9 @@
 {#
-SPDX-FileCopyrightText: 2023 - 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+SPDX-FileCopyrightText: 2023 - 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 #}
 
 include:
-  - dotfiles.copy-xfce
   - dotfiles.copy-x11
+  - utils.tools.xfce

salt/sys-syncthing/install.sls

@@ -1,17 +1,18 @@
 {#
 SPDX-FileCopyrightText: 2022 - 2023 unman <unman@thirdeyesecurity.org>
-SPDX-FileCopyrightText: 2023 - 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+SPDX-FileCopyrightText: 2023 - 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 #}
 
 {% if grains['nodename'] != 'dom0' -%}
 
-{% if grains['os_family']|lower == 'debian' -%}
 include:
+{% if grains['os_family']|lower == 'debian' -%}
   - .install-repo
   - utils.tools.common.update
 {% endif -%}
+  - utils.tools.xfce
 
 "{{ slsdotpath }}-installed":
   pkg.installed:

salt/utils/tools/helpers/README.md

@@ -0,0 +1,61 @@
+# helpers
+
+Add helper scripts.
+
+## Table of Contents
+
+*   [Description](#description)
+*   [Installation](#installation)
+*   [Usage](#usage)
+
+## Description
+
+Wrappers that help run applications available, either being terminals,
+browsers, file manager or mail user agents. It is possible to try a specific
+program by setting environment variables specific to each helper.
+
+## Installation
+
+*   Top:
+
+```sh
+sudo qubesctl top.enable utils.tools.helpers
+sudo qubesctl --targets=TARGET state.apply
+sudo qubesctl top.disable utils.tools.helpers
+```
+
+*   State:
+
+<!-- pkg:begin:post-install -->
+
+```sh
+sudo qubesctl --skip-dom0 --targets=TEMPLATEVMS,APPVMS state.apply utils.tools.helpers
+```
+
+<!-- pkg:end:post-install -->
+
+## Usage
+
+Open a terminal:
+
+```sh
+run-terminal
+```
+
+Open a browser:
+
+```sh
+run-browser https://example.org
+```
+
+Open mail user agent program:
+
+```sh
+run-mail
+```
+
+Open file manager on a specific directory:
+
+```sh
+run-file-manager ~/
+```

salt/utils/tools/helpers/files/bin/run-browser

@@ -0,0 +1 @@
+run-terminal

salt/utils/tools/helpers/files/bin/run-file-manager

@@ -0,0 +1 @@
+run-terminal

salt/utils/tools/helpers/files/bin/run-mail

@@ -0,0 +1 @@
+run-terminal

salt/utils/tools/helpers/files/bin/run-terminal

@@ -0,0 +1,121 @@
+#!/bin/sh
+
+## SPDX-FileCopyrightText: 2018 - 2025 The Qubes OS Project <https://www.qubes-os.org>
+## SPDX-FileCopyrightText: 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+##
+## SPDX-License-Identifier: AGPL-3.0-or-later
+
+## Debian has x-terminal-emulator to set default one.
+## Qubes has qubes-run-terminal to get beginner friendly one.
+## Most OSes do not have a wrapper, create one.
+
+set -eu
+
+has(){
+  if ! command -v "${1}" >/dev/null; then
+    if test "${DEBUG-}" = "1"; then
+      printf '%s\n' "debug: command not found: ${prog}" >&2
+    fi
+    return 1
+  fi
+}
+
+exec_has(){
+  prog="${1}"
+  shift
+  # shellcheck disable=SC2310
+  if has "${prog}"; then
+    if test "${DEBUG-}" = "1"; then
+      printf '%s\n' "debug: executing: ${prog} ${*}" >&2
+    fi
+    exec "${prog}" "${@}"
+  fi
+}
+
+run_term_gnome(){
+  case "${1}" in
+    gnome-terminal) ghelp="$("${1}" --help-terminal-options)";;
+    kgx) ghelp="$("${1}" --help)";;
+    *) printf '%s\n' "error: unsupported GNOME terminal" >&2; exit 1;;
+  esac
+  case "${ghelp}" in
+    *--wait\ *) exec "${1}" --wait "${@}";;
+    *) exec "${1}" "${@}";;
+  esac
+}
+
+run(){
+  case "${wanted_program}" in
+    terminal) env_prog="${TERMINAL:-}";;
+    file-manager) env_prog="${FILE_MANAGER:-}";;
+    browser) env_prog="${BROWSER:-}";;
+    mail) env_prog="${MAIL_USER_AGENT:-}";;
+    *) printf '%s\n' "error: invalid program type ${wanted_program}"; exit 1;;
+  esac
+  for prog in "${env_prog}" ${programs}; do
+    # shellcheck disable=SC2310
+    has "${prog}" || continue
+    case "${wanted_program}" in
+      terminal)
+        case "${prog}" in
+          gnome-terminal|kgx) run_term_gnome "${prog}" "${@}";;
+          *);;
+        esac
+        ;;
+      file-manager)
+        ## Required by 'xdg-open'.
+        if test "${#}" = "0"; then
+          set -- .
+        fi
+        ;;
+      browser)
+        if test "${prog}" = "xdg-open" && test "${#}" = "0"; then
+          continue
+        fi
+        ;;
+      *);;
+    esac
+    exec_has "${prog}" "${@}"
+  done
+  printf '%s\n' "error: no ${wanted_program} program found" >&2
+  exit 1
+}
+
+usage(){
+  case "${wanted_program}" in
+    terminal) set -- "\$TERMINAL";;
+    file-manager) set -- "\$FILE_MANAGER";;
+    browser) set -- "\$BROWSER";;
+    mail) set -- "\$MAIL_USER_AGENT";;
+    *) printf '%s\n' "error: invalid program type ${wanted_program}"; exit 1;;
+  esac
+  set -- "${@}" "${programs}"
+  printf '%s\n' "Usage: ${0##*/} [ARGS...]
+Action: Run the first ${wanted_program} found with the arguments provided.
+Order: ${*}" >&2
+  exit 1
+}
+
+terminals="x-terminal-emulator ptyxis gnome-terminal kgx
+xfce4-terminal konsole termit terminator Eterm aterm roxterm termite
+lxterminal mate-terminal terminology st urxvt rxvt lxterm xterm"
+file_managers="xdg-open thunar nautilus caja"
+browsers="xdg-open chrome chromium mullvad-browser firefox
+firefox-esr w3m elinks links lynx"
+mail_user_agents="thunderbird mutt"
+
+wanted_program="${0##*/run-}"
+case "${wanted_program}" in
+  terminal) programs="${terminals}";;
+  file-manager) programs="${file_managers}";;
+  browser) programs="${browsers}";;
+  mail) programs="${mail_user_agents}";;
+  *) printf '%s\n' "error: invalid script name: ${0##*/}"; exit 1;;
+esac
+case "${1:-}" in
+  -\?|--?help|help) usage;;
+  "");;
+  *);;
+esac
+
+run "${@}"

salt/utils/tools/helpers/init.sls

@@ -0,0 +1,16 @@
+{#
+SPDX-FileCopyrightText: 2024 - 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+#}
+
+"{{ slsdotpath }}-helpers":
+  file.recurse:
+    - name: /usr/bin/
+    - source: salt://utils/tools/helpers/files/bin
+    - user: root
+    - group: root
+    - file_mode: '0755'
+    - dir_mode: '0755'
+    - keep_symlinks: True
+    - force_symlinks: True

salt/utils/tools/helpers/init.top

@@ -0,0 +1,9 @@
+{#
+SPDX-FileCopyrightText: 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+#}
+
+base:
+  '*':
+    - utils.tools.helpers

salt/utils/tools/xfce/README.md

@@ -0,0 +1,37 @@
+# xfce
+
+Xfce environment in Qubes OS.
+
+## Table of Contents
+
+*   [Description](#description)
+*   [Installation](#installation)
+*   [Usage](#usage)
+
+## Description
+
+Configure Xfce.
+
+## Installation
+
+*   Top:
+
+```sh
+sudo qubesctl top.enable utils.tools.xfce
+sudo qubesctl --targets=TARGET state.apply
+sudo qubesctl top.disable utils.tools.xfce
+```
+
+*   State:
+
+<!-- pkg:begin:post-install -->
+
+```sh
+sudo qubesctl --skip-dom0 --targets=TEMPLATEVMS,APPVMS state.apply utils.tools.xfce
+```
+
+<!-- pkg:end:post-install -->
+
+## Usage
+
+Standard Xfce usage. No extra configuration required.

salt/utils/tools/xfce/files/helpers.rc

@@ -0,0 +1,9 @@
+## SPDX-FileCopyrightText: 2024 - 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+##
+## SPDX-License-Identifier: AGPL-3.0-or-later
+# vim: ft=confini
+
+FileManager=run-file-manager
+MailReaders=run-mail
+WebBrowser=run-browser
+TerminalEmulator=run-terminal

salt/utils/tools/xfce/init.sls

@@ -0,0 +1,44 @@
+{#
+SPDX-FileCopyrightText: 2024 - 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+#}
+
+{%- import "dom0/gui-user.jinja" as gui_user -%}
+
+include:
+  - utils.tools.helpers
+
+"{{ slsdotpath }}-makedir-config-xfce":
+  file.directory:
+    - name: {{ gui_user.gui_user_home }}/.config/xfce4/
+    - mode: '0755'
+    - user: {{ gui_user.gui_user }}
+    - group: {{ gui_user.gui_user }}
+    - makedirs: True
+
+"{{ slsdotpath }}-copy-home":
+  file.recurse:
+    - require:
+      - file: "{{ slsdotpath }}-makedir-config-xfce"
+    - name: {{ gui_user.gui_user_home }}/.config/xfce4/
+    - source: salt://utils/tools/xfce/files/
+    - file_mode: '0644'
+    - dir_mode: '0700'
+    - user: {{ gui_user.gui_user }}
+    - group: {{ gui_user.gui_user }}
+    - keep_symlinks: True
+    - force_symlinks: True
+
+"{{ slsdotpath }}-copy-skel":
+  file.recurse:
+    - require:
+      - file: "{{ slsdotpath }}-makedir-config-xfce"
+    - name: /etc/skel/.config/xfce4/
+    - source: salt://utils/tools/xfce/files/
+    - file_mode: '0644'
+    - dir_mode: '0700'
+    - user: root
+    - group: root
+    - keep_symlinks: True
+    - force_symlinks: True

salt/utils/tools/xfce/init.top

@@ -0,0 +1,9 @@
+{#
+SPDX-FileCopyrightText: 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+#}
+
+base:
+  '*':
+    - utils.tools.xfce