feat: add file-manager right-click action for PDFsHEADmaster

pput.desktop is a DES-EMA action exposing "Upload to Paperless" on the
context menu for application/pdf, using %F so a whole selection uploads
in one click, not just a single file.

It runs pput-gui rather than pput directly: a click has no terminal, so
the wrapper reports the outcome through notify-send, falling back to
zenity. It also sets PINENTRY_USER_DATA, since pass(1) needs a GUI
pinentry when there is no controlling terminal.

Exec= calls pput-gui by name rather than by absolute path, matching the
other actions in this format and keeping a user's home out of the file.

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

1 files changed, 50 insertions, 0 deletions

diff --git a/pput-gui b/pput-gui
new file mode 100755
index 0000000..31d9e53
--- /dev/null
+++ b/pput-gui
@@ -0,0 +1,50 @@
+#!/bin/bash
+#
+# pput-gui - pput wrapper for file-manager right-click actions
+#
+# 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 as published by
+# the Free Software Foundation; version 2 of the License.
+#
+# 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.
+#
+# Usage: pput-gui FILE [FILE...]
+#
+# Runs pput on the selection and reports the result as a desktop
+# notification, since a file-manager click has no terminal to print to.
+
+set -uo pipefail
+
+notify() {  # notify(urgency, title, body)
+    notify-send -a pput -u "$1" "$2" "$3" 2>/dev/null \
+        || zenity --info --title="$2" --text="$3" 2>/dev/null \
+        || true
+}
+
+[ $# -gt 0 ] || { notify critical "pput" "No files selected."; exit 2; }
+
+# ponytail: pass(1) needs a gpg-agent with a usable pinentry. From a file
+# manager there is no controlling terminal, so point at the GUI pinentry.
+export GPG_TTY=""
+export PINENTRY_USER_DATA="${PINENTRY_USER_DATA:-gui}"
+
+out=$(pput "$@" 2>&1); rc=$?
+
+ok=$(printf '%s\n' "$out" | grep -c '^OK ')
+bad=$(printf '%s\n' "$out" | grep -cE '^(FAIL|TIMEOUT|skip) ')
+
+if [ "$rc" -eq 0 ]; then
+    notify normal "Paperless: $ok uploaded" "$out"
+else
+    notify critical "Paperless: $ok uploaded, $bad failed" "$out"
+fi
+exit $rc