feat(signal): route message toasts through the notify script

Incoming messages now notify through cj/signel--notify, installed as the fork's signel-notify-function. It suppresses the toast while that chat is in the selected window of a focused frame, collapses and truncates the body to 120 characters, and sends through the notify script (info type, --silent unless cj/signel-notify-sound is set). Without the script on PATH it falls back to notifications-notify and warns at load. The decisions are in the Notification slice addendum of docs/design/signal-client.org.
author: Craig Jennings <c@cjennings.net> 2026-06-11 12:07:04 -0500
committer: Craig Jennings <c@cjennings.net> 2026-06-11 12:07:04 -0500
commit: 9afc61288d0de7c7e2649a2730c57e642ac77c01 (patch)
tree: 31a64022677aaf61686f97e6b366bd36a838dd28
parent: 4003f40ca129f434f85f14e5dfe13655c4e15258 (diff)
download: dotemacs-9afc61288d0de7c7e2649a2730c57e642ac77c01.tar.gz
dotemacs-9afc61288d0de7c7e2649a2730c57e642ac77c01.zip
4 files changed, 311 insertions, 1 deletions
diff --git a/docs/design/signal-client.org b/docs/design/signal-client.org
index 24503ec03..ef946b80c 100644
--- a/docs/design/signal-client.org
+++ b/docs/design/signal-client.org
@@ -226,3 +226,25 @@ Notification-slice forward-flag: the existing Design notes route notifications t
 ** Readiness rubric
 
 *Ready* (2026-05-27 spec-review). All three Codex blockers folded in (Architecture additions); the final sync/async decision resolved as pre-warm + bounded block; three minor caveats stated for build time, none blocking. Implementation order follows the Pieces-to-build list — the JSON-RPC result-dispatch fork edit is step 1, everything else builds on it.
+
+* Notification slice (spec addendum — 2026-06-11)
+
+Resolves the four details the forward-flag in Scope summary required before this slice starts. Craig accepted all four recommendations 2026-06-11.
+
+** The four decisions
+
+1. *Command shape.* =notify info "Signal: <sender>" "<body>"=, launched via =start-process= so the receive filter never blocks on the script. Type =info= (blue icon, confident tone). No =--persist=: messages arrive as a stream and persistent toasts pile up; a missed toast is still in the chat buffer, unlike an alarm. Sound follows =cj/signel-notify-sound= (defcustom, default nil): pass =--silent= unless it is non-nil.
+2. *Fallback when =notify= is missing.* Warn once at module load via =cj/executable-find-or-warn= (the established external-tool pattern), and at runtime fall back to the fork's =notifications-notify= call so an incoming message is never silently dropped on a machine without the script.
+3. *Body truncation.* Collapse whitespace runs (including newlines) to single spaces and truncate to 120 characters with an ellipsis. Long messages flood the toast and the daemon clips unpredictably; the full text is always in the chat buffer.
+4. *Verbatim text.* Show the (truncated) message text verbatim. Same accept-and-state stance as the =*signel-log*= caveat — single-user local machine. Revisit if notifications ever route off-machine.
+
+** Wiring architecture
+
+The fork stays generic; the policy lives in =signal-config.el=:
+
+- *Fork edit* — =signel.el= gains =signel-notify-function= (defvar, default =signel--notify-default= which preserves today's bare =notifications-notify= behavior). =signel--handle-receive='s notify block becomes =(funcall signel-notify-function chat-id sender notify-body)= — chat-id added so a custom function can make per-chat decisions. The fork never references cj/ symbols and remains loadable standalone.
+- *cj layer* — =cj/signel--notify= (set as =signel-notify-function= in the use-package =:config=) gates on =cj/signal--should-notify-p= (the existing suppression predicate), formats the body via a pure helper (=cj/signal--format-notify-body=: whitespace collapse + 120-char truncation), and routes: =notify= script when =executable-find= sees it, =notifications-notify= fallback otherwise.
+
+** Testing
+
+ERT, no live account: the body formatter (Normal/Boundary — passthrough, newline collapse, exact-limit, over-limit + ellipsis, empty, unicode); =cj/signel--notify= routing (suppressed when the predicate says no; script path args including =--silent= by default and its absence when sound is enabled; fallback path when the script is missing); the fork dispatch (a text message calls =signel-notify-function= with chat-id/sender/body; sticker → "[Sticker]"; attachment → "[Attachment]"; default function preserved). Manual: a real incoming message raises the toast through the script; no toast while viewing that chat in a focused frame.
diff --git a/modules/signal-config.el b/modules/signal-config.el
index 317e35203..7e980b62e 100644
--- a/modules/signal-config.el
+++ b/modules/signal-config.el
@@ -17,6 +17,9 @@
 
 (require 'seq)
 (require 'keybindings)  ;; provides cj/custom-keymap + cj/register-prefix-map
+(require 'system-lib)   ;; for cj/executable-find-or-warn
+
+(declare-function notifications-notify "notifications")
 
 (defun cj/signal--jstr (value)
   "Return VALUE if it is a non-blank string, else nil.
@@ -102,6 +105,46 @@ window of a focused frame."
         (buffer-name (window-buffer (selected-window)))
         (cj/signal--frame-focused-p))))
 
+;;; Notifications
+
+(defcustom cj/signel-notify-sound nil
+  "When non-nil, incoming-message notifications play the notify script's sound.
+Nil (the default) passes --silent so the toast is visual only."
+  :type 'boolean
+  :group 'signel)
+
+(defconst cj/signal--notify-body-max 120
+  "Maximum character length of a desktop-notification body.
+Longer message text truncates to this length ending in an ellipsis;
+the full text is always in the chat buffer.")
+
+(defun cj/signal--format-notify-body (text)
+  "Collapse whitespace in TEXT and truncate it for a notification body.
+Whitespace runs (including newlines) become single spaces, the result
+is trimmed, and anything over `cj/signal--notify-body-max' characters
+truncates to that length with a trailing ellipsis."
+  (let ((flat (string-trim (replace-regexp-in-string "[ \t\n\r]+" " " text))))
+    (if (<= (length flat) cj/signal--notify-body-max)
+        flat
+      (concat (substring flat 0 (1- cj/signal--notify-body-max)) "…"))))
+
+(defun cj/signel--notify (chat-id sender body)
+  "Raise a desktop notification for an incoming Signal message.
+Suppressed via `cj/signal--should-notify-p' when the user is actively
+viewing CHAT-ID.  Routes through the external notify script when it is
+on PATH (type info, sound gated by `cj/signel-notify-sound'), falling
+back to `notifications-notify' otherwise.  SENDER names the title;
+BODY is formatted by `cj/signal--format-notify-body'.  Installed as
+`signel-notify-function' in the use-package :config below."
+  (when (cj/signal--should-notify-p chat-id)
+    (let ((title (format "Signal: %s" sender))
+          (text (cj/signal--format-notify-body body))
+          (script (executable-find "notify")))
+      (if script
+          (apply #'start-process "signel-notify" nil script "info" title text
+                 (unless cj/signel-notify-sound (list "--silent")))
+        (notifications-notify :title title :body text)))))
+
 ;;; signel — fork integration
 
 (defcustom cj/signal-private-config-file
@@ -126,7 +169,13 @@ time."
   (signel-auto-open-buffer nil)
   :config
   (when (file-readable-p cj/signal-private-config-file)
-    (load cj/signal-private-config-file nil t)))
+    (load cj/signal-private-config-file nil t))
+  ;; Route incoming-message notifications through cj/signel--notify
+  ;; (suppression + notify script + truncation); warn once at load when
+  ;; the script is missing — the runtime path still falls back to
+  ;; notifications-notify, so messages are never silently dropped.
+  (setq signel-notify-function #'cj/signel--notify)
+  (cj/executable-find-or-warn "notify" "Signal desktop notifications via the notify script (falling back to notifications-notify)" 'signal-config))
 
 ;; Chat buffers (named `*Signel: <id>*') open in the bottom 30% of the
 ;; frame rather than wherever display-buffer's fallback rule picks.
diff --git a/tests/test-signal-config-notify.el b/tests/test-signal-config-notify.el
new file mode 100644
index 000000000..c4067a663
--- /dev/null
+++ b/tests/test-signal-config-notify.el
@@ -0,0 +1,150 @@
+;;; test-signal-config-notify.el --- Tests for the signal-config notification slice -*- lexical-binding: t -*-
+
+;;; Commentary:
+;; ERT tests for the notification slice of `signal-config': the pure
+;; body formatter (whitespace collapse + truncation to
+;; `cj/signal--notify-body-max') and `cj/signel--notify' routing (the
+;; suppression gate, the notify-script path with the sound flag, and
+;; the `notifications-notify' fallback).  Spec: the "Notification
+;; slice" addendum in docs/design/signal-client.org.  No signal-cli or
+;; linked account needed.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+;; signel is the fork at ~/code/signel; signal-config wires it via
+;; use-package but these tests need the symbols available directly.
+(eval-and-compile
+  (add-to-list 'load-path (expand-file-name "~/code/signel")))
+(require 'signel)
+
+(require 'signal-config)
+
+;;; cj/signal--format-notify-body
+
+(ert-deftest test-signal-config-format-notify-body-passthrough ()
+  "Normal: short single-line text passes through unchanged."
+  (should (equal (cj/signal--format-notify-body "lunch at noon?")
+                 "lunch at noon?")))
+
+(ert-deftest test-signal-config-format-notify-body-collapses-whitespace ()
+  "Normal: newlines and whitespace runs collapse to single spaces."
+  (should (equal (cj/signal--format-notify-body "two\nlines\n\nhere")
+                 "two lines here"))
+  (should (equal (cj/signal--format-notify-body "tabs\t\tand   spaces")
+                 "tabs and spaces")))
+
+(ert-deftest test-signal-config-format-notify-body-trims ()
+  "Boundary: leading and trailing whitespace is trimmed."
+  (should (equal (cj/signal--format-notify-body "  hi  ") "hi")))
+
+(ert-deftest test-signal-config-format-notify-body-empty ()
+  "Boundary: the empty string stays empty."
+  (should (equal (cj/signal--format-notify-body "") "")))
+
+(ert-deftest test-signal-config-format-notify-body-exact-limit ()
+  "Boundary: a body exactly at the limit is untouched."
+  (let ((s (make-string cj/signal--notify-body-max ?x)))
+    (should (equal (cj/signal--format-notify-body s) s))))
+
+(ert-deftest test-signal-config-format-notify-body-truncates-over-limit ()
+  "Boundary: over-limit text truncates to the limit, ending in an ellipsis."
+  (let* ((s (make-string (1+ cj/signal--notify-body-max) ?x))
+         (out (cj/signal--format-notify-body s)))
+    (should (= (length out) cj/signal--notify-body-max))
+    (should (string-suffix-p "…" out))))
+
+(ert-deftest test-signal-config-format-notify-body-unicode ()
+  "Boundary: multibyte text truncates by characters, not bytes."
+  (let* ((s (make-string (+ cj/signal--notify-body-max 10) ?é))
+         (out (cj/signal--format-notify-body s)))
+    (should (= (length out) cj/signal--notify-body-max))
+    (should (string-suffix-p "…" out))))
+
+;;; cj/signel--notify routing
+
+(ert-deftest test-signal-config-notify-suppressed-when-viewing ()
+  "Normal: nothing fires when the suppression predicate says no."
+  (let (script-calls fallback-calls)
+    (cl-letf (((symbol-function 'cj/signal--should-notify-p)
+               (lambda (_chat-id) nil))
+              ((symbol-function 'start-process)
+               (lambda (&rest args) (push args script-calls) nil))
+              ((symbol-function 'notifications-notify)
+               (lambda (&rest args) (push args fallback-calls) nil)))
+      (cj/signel--notify "+15551234567" "Alice" "hi"))
+    (should-not script-calls)
+    (should-not fallback-calls)))
+
+(ert-deftest test-signal-config-notify-script-silent-by-default ()
+  "Normal: with the script present and sound off, runs notify info --silent."
+  (let (script-calls)
+    (cl-letf (((symbol-function 'cj/signal--should-notify-p)
+               (lambda (_chat-id) t))
+              ((symbol-function 'executable-find)
+               (lambda (p &optional _remote)
+                 (when (equal p "notify") "/usr/bin/notify")))
+              ((symbol-function 'start-process)
+               (lambda (&rest args) (push args script-calls) nil))
+              ((symbol-function 'notifications-notify)
+               (lambda (&rest _)
+                 (error "Fallback must not fire when the script is present"))))
+      (let ((cj/signel-notify-sound nil))
+        (cj/signel--notify "+15551234567" "Alice" "hi")))
+    (should (= (length script-calls) 1))
+    ;; start-process args: (NAME BUFFER PROGRAM &rest PROGRAM-ARGS);
+    ;; PROGRAM is the path executable-find resolved, not the bare name.
+    (should (equal (nthcdr 2 (car script-calls))
+                   '("/usr/bin/notify" "info" "Signal: Alice" "hi" "--silent")))))
+
+(ert-deftest test-signal-config-notify-sound-enabled-drops-silent ()
+  "Normal: with `cj/signel-notify-sound' non-nil, --silent is omitted."
+  (let (script-calls)
+    (cl-letf (((symbol-function 'cj/signal--should-notify-p)
+               (lambda (_chat-id) t))
+              ((symbol-function 'executable-find)
+               (lambda (p &optional _remote)
+                 (when (equal p "notify") "/usr/bin/notify")))
+              ((symbol-function 'start-process)
+               (lambda (&rest args) (push args script-calls) nil)))
+      (let ((cj/signel-notify-sound t))
+        (cj/signel--notify "+15551234567" "Alice" "hi")))
+    (should (equal (nthcdr 2 (car script-calls))
+                   '("/usr/bin/notify" "info" "Signal: Alice" "hi")))))
+
+(ert-deftest test-signal-config-notify-fallback-when-script-missing ()
+  "Error: without the script on PATH, falls back to notifications-notify."
+  (let (script-calls fallback-calls)
+    (cl-letf (((symbol-function 'cj/signal--should-notify-p)
+               (lambda (_chat-id) t))
+              ((symbol-function 'executable-find)
+               (lambda (_p &optional _remote) nil))
+              ((symbol-function 'start-process)
+               (lambda (&rest args) (push args script-calls) nil))
+              ((symbol-function 'notifications-notify)
+               (lambda (&rest args) (push args fallback-calls) nil)))
+      (cj/signel--notify "+15551234567" "Alice" "hi"))
+    (should-not script-calls)
+    (should (= (length fallback-calls) 1))
+    (let ((args (car fallback-calls)))
+      (should (equal (plist-get args :title) "Signal: Alice"))
+      (should (equal (plist-get args :body) "hi")))))
+
+(ert-deftest test-signal-config-notify-formats-body-before-send ()
+  "Normal: the body runs through the formatter before reaching the script."
+  (let (script-calls)
+    (cl-letf (((symbol-function 'cj/signal--should-notify-p)
+               (lambda (_chat-id) t))
+              ((symbol-function 'executable-find)
+               (lambda (p &optional _remote)
+                 (when (equal p "notify") "/usr/bin/notify")))
+              ((symbol-function 'start-process)
+               (lambda (&rest args) (push args script-calls) nil)))
+      (let ((cj/signel-notify-sound nil))
+        (cj/signel--notify "+15551234567" "Alice" "first line\nsecond line")))
+    (should (equal (nth 5 (car script-calls)) "first line second line"))))
+
+(provide 'test-signal-config-notify)
+;;; test-signal-config-notify.el ends here
diff --git a/tests/test-signel-notify-function.el b/tests/test-signel-notify-function.el
new file mode 100644
index 000000000..cff7f7394
--- /dev/null
+++ b/tests/test-signel-notify-function.el
@@ -0,0 +1,89 @@
+;;; test-signel-notify-function.el --- Tests for signel's notify-function dispatch -*- lexical-binding: t -*-
+
+;;; Commentary:
+;; signel's receive handler (signel.el in the fork at ~/code/signel)
+;; raised notifications through a hardwired `notifications-notify'
+;; call.  The notification slice (docs/design/signal-client.org,
+;; "Notification slice" addendum) replaces that with
+;; `signel-notify-function', a customization point called with
+;; CHAT-ID, SENDER, and BODY so a config layer can add suppression or
+;; route through an external notifier.  These tests cover the
+;; dispatch: text, sticker, and attachment bodies reach the function
+;; with the right arguments, and the default preserves the plain
+;; `notifications-notify' behavior.
+;;
+;; `signel--handle-receive' is exercised directly with synthetic
+;; envelope alists; buffer/dashboard side effects are stubbed.  No
+;; live process needed.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(eval-and-compile
+  (add-to-list 'load-path (expand-file-name "~/code/signel")))
+(require 'signel)
+
+(defun test-signel-notify--receive (envelope)
+  "Run `signel--handle-receive' on ENVELOPE, capturing notify calls.
+Returns the list of (CHAT-ID SENDER BODY) argument lists the handler
+passed to `signel-notify-function', oldest first.  Buffer and
+dashboard side effects are stubbed out."
+  (let (calls)
+    (cl-letf (((symbol-function 'signel--insert-msg) (lambda (&rest _) nil))
+              ((symbol-function 'signel--dashboard-refresh) (lambda () nil))
+              ((symbol-function 'signel--get-buffer)
+               (lambda (_) (current-buffer))))
+      (let ((signel-notify-function
+             (lambda (chat-id sender body)
+               (push (list chat-id sender body) calls)))
+            (signel-auto-open-buffer nil))
+        (signel--handle-receive `((envelope . ,envelope)))))
+    (nreverse calls)))
+
+(ert-deftest test-signel-notify-function-text-message ()
+  "Normal: a text dataMessage calls the function with chat-id, sender, text."
+  (should (equal (test-signel-notify--receive
+                  '((sourceNumber . "+15551234567")
+                    (sourceName . "Alice")
+                    (dataMessage . ((message . "hi there")))))
+                 '(("+15551234567" "Alice" "hi there")))))
+
+(ert-deftest test-signel-notify-function-sticker-placeholder ()
+  "Boundary: a sticker with no text gets the [Sticker] placeholder body."
+  (should (equal (test-signel-notify--receive
+                  '((sourceNumber . "+15551234567")
+                    (sourceName . "Alice")
+                    (dataMessage . ((sticker . ((packId . "p1")))))))
+                 '(("+15551234567" "Alice" "[Sticker]")))))
+
+(ert-deftest test-signel-notify-function-attachment-placeholder ()
+  "Boundary: an attachment with no text gets the [Attachment] placeholder."
+  (should (equal (test-signel-notify--receive
+                  '((sourceNumber . "+15551234567")
+                    (sourceName . "Alice")
+                    (dataMessage . ((attachments . [((id . "a1"))])))))
+                 '(("+15551234567" "Alice" "[Attachment]")))))
+
+(ert-deftest test-signel-notify-function-no-data-no-call ()
+  "Boundary: an envelope with no dataMessage never calls the function."
+  (should-not (test-signel-notify--receive
+               '((sourceNumber . "+15551234567")
+                 (sourceName . "Alice")
+                 (typingMessage . ((action . "STARTED")))))))
+
+(ert-deftest test-signel-notify-function-default-preserves-behavior ()
+  "Normal: the default value raises a plain notifications-notify toast."
+  (should (eq signel-notify-function #'signel--notify-default))
+  (let (calls)
+    (cl-letf (((symbol-function 'notifications-notify)
+               (lambda (&rest args) (push args calls) nil)))
+      (signel--notify-default "+15551234567" "Alice" "hi"))
+    (should (= (length calls) 1))
+    (let ((args (car calls)))
+      (should (equal (plist-get args :title) "Signel: Alice"))
+      (should (equal (plist-get args :body) "hi")))))
+
+(provide 'test-signel-notify-function)
+;;; test-signel-notify-function.el ends here
author	Craig Jennings <c@cjennings.net>	2026-06-11 12:07:04 -0500
committer	Craig Jennings <c@cjennings.net>	2026-06-11 12:07:04 -0500
commit	9afc61288d0de7c7e2649a2730c57e642ac77c01 (patch)
tree	31a64022677aaf61686f97e6b366bd36a838dd28
parent	4003f40ca129f434f85f14e5dfe13655c4e15258 (diff)
download	dotemacs-9afc61288d0de7c7e2649a2730c57e642ac77c01.tar.gz dotemacs-9afc61288d0de7c7e2649a2730c57e642ac77c01.zip