feat: Add :admin-bcc option for notification subscribers

Author: bzg

config.edn.example

@@ -208,7 +208,11 @@
  ;;                        :tls      true
  ;;                        :user     "notify@example.com"
  ;;                        :password "secret"
- ;;                        :from     "bark@example.com"}}
+ ;;                        :from     "bark@example.com"}
+ ;;                 ;; Optional -- copy this address (or vector of
+ ;;                 ;; addresses) on every notification (subscriber
+ ;;                 ;; digest and direct-to-author failure mail).
+ ;;                 :admin-bcc "ops@example.com"}
 
  ;; ---- Logging -------------------------------------------------------------
 

docs/bark-manual.org

@@ -584,7 +584,7 @@ urgent or important, and can still be closed.
 =Urgent= and =Important= require punctuation (=.= =,= =;= =:= =?=
 =!=) or end of line.  A bare space is rejected, since words like
 "Important" appear too frequently in ordinary prose to be safe
-triggers.
+bareword annotations.
 
 These two values combine into the numeric priority:
 
@@ -1099,6 +1099,7 @@ limit with =:max-attachment-size= in the =:ingest= config section.
         :password "secret"
         :from     "bark@example.com"
         :reply-to "lead@example.com"}   ;; optional
+ :admin-bcc "ops@example.com"           ;; optional; string or vector
  :subscribers
  {"a@example.org"
   [{:source "my-list"}]
@@ -1112,6 +1113,11 @@ associated vector lists their subscriptions, one per source --
 a recipient on three sources receives three separate emails per
 =bb notify= run.
 
+=:admin-bcc= adds a hidden carbon-copy on every subscriber digest.
+A single address as a string, or a vector of addresses.  Useful to
+audit deliverability and to catch bounces.  The BCC field is not
+visible to the other recipients (standard SMTP semantics).
+
 Optional per-subscription filters:
 
 | Key            | Description                                                  |
@@ -1136,6 +1142,13 @@ records the last successful send per (subscriber, source) so the
 same failed-command entries are not re-mailed at every run.  Delete
 the file to replay all current failures on the next invocation.
 
+Command failures are kept on file for the subscriber digest and for
+manual inspection via =bb maintenance --failures=.  BARK does *not*
+mail the author of a failing command directly: an unsubscribed user
+who typed =Superseded-by:= with a typo learns of the failure only
+if they are themselves on the subscriber list.  Maintainers see all
+failures with =:audience :maintainers= in their digest.
+
 ** Logging
 
 #+begin_src edn

scripts/bark-notify.clj

@@ -43,8 +43,8 @@
 ;;
 ;; We persist the timestamp of the last successful notification per
 ;; (subscriber, source) pair to avoid re-sending the same failure on
-;; every run.  This is operational state, not configuration -- subscriber
-;; identity and filters live in config.edn.
+;; every run.  This is operational state, not configuration --
+;; subscribers and filters live in config.edn.
 
 (def ^:private last-failures-file "public/.last-notify-failures.edn")
 
@@ -238,8 +238,8 @@
            "\n"))))
 
 (defn- join-sections
-  "Concatenate the non-nil sections with blank-line separators and append
-  a short footer.  Returns nil when every section is nil."
+  "Concatenate the non-nil sections with blank-line separators and
+  append a short footer.  Returns nil when every section is nil."
   [sections]
   (let [present (filter some? sections)]
     (when (seq present)
@@ -278,10 +278,24 @@
 ;; SMTP
 ;; ---------------------------------------------------------------------------
 
+(defn- bcc-list
+  "Normalize `:admin-bcc` to a vector of addresses (or nil when absent).
+  Accepts a single string or a vector of strings."
+  [admin-bcc]
+  (cond
+    (nil? admin-bcc)         nil
+    (string? admin-bcc)      [admin-bcc]
+    (sequential? admin-bcc)  (vec admin-bcc)
+    :else                    (do (log/warn "Ignoring invalid :admin-bcc"
+                                           (pr-str admin-bcc))
+                                 nil)))
+
 (defn send-notification!
-  "Send a plain-text notification email via SMTP."
-  [smtp-config to-addr source body]
-  (let [{:keys [host port tls user password from reply-to]} smtp-config]
+  "Send a plain-text notification email via SMTP.
+  `admin-bcc` is forwarded as :bcc on every send when non-nil."
+  [smtp-config to-addr source body admin-bcc]
+  (let [{:keys [host port tls user password from reply-to]} smtp-config
+        bccs (bcc-list admin-bcc)]
     (mail/send-mail
      (cond-> {:host     host
               :port     port
@@ -292,7 +306,8 @@
               :to       [to-addr]
               :subject  (str "[BARK " source "] Open reports")
               :text     body}
-       reply-to (assoc :reply-to reply-to)))))
+       reply-to    (assoc :reply-to reply-to)
+       (seq bccs)  (assoc :bcc bccs)))))
 
 ;; ---------------------------------------------------------------------------
 ;; Main
@@ -318,6 +333,7 @@
         dbp         (db-path config)
         notif       (:notifications config)
         smtp        (:smtp notif)
+        admin-bcc   (:admin-bcc notif)
         subscribers (:subscribers notif)]
     (cond
       (not (and notif (:enabled notif)))
@@ -365,7 +381,7 @@
                                   "Notifying" email (str "(source: " source ")"))
                         (when-not dry-run?
                           (try
-                            (send-notification! smtp email source body)
+                            (send-notification! smtp email source body admin-bcc)
                             (swap! updated-shown assoc k (.getTime (java.util.Date.)))
                             (swap! sent inc)
                             (catch Exception e

scripts/validate-config.clj

@@ -155,6 +155,14 @@
                            :opt-un [:smtp/tls :smtp/reply-to]))
 (s/def :notif/enabled boolean?)
 
+;; Admin Bcc: single email or non-empty vector of emails, copied on
+;; every outgoing subscriber digest.  Lets the operator audit
+;; deliverability without subscribing each admin on each source
+;; individually.
+(s/def :notif/admin-bcc
+  (s/or :one  ::email
+        :many (s/coll-of ::email :kind vector? :min-count 1)))
+
 ;; Subscriber filters (all optional except :source)
 (s/def :sub/source ::non-blank-string)
 (s/def :sub/min-priority (s/and int? #(<= 0 % 3)))
@@ -169,7 +177,7 @@
             (s/coll-of :notif/subscription :kind vector? :min-count 1)))
 
 (s/def :bark/notifications (s/keys :req-un [:notif/enabled]
-                                   :opt-un [:notif/smtp :notif/subscribers]))
+                                   :opt-un [:notif/smtp :notif/subscribers :notif/admin-bcc]))
 
 ;; Valid report type keywords -- derived from common/report-type-spec.
 (def valid-report-types common/report-type-keywords)

src/bark/commands.clj

@@ -260,27 +260,23 @@
               :unset-expiry   (-> acc (dissoc :expiry) (assoc :unexpiry? true))
               :set-topic      (assoc acc :topic topic)
               :unset-topic    (-> acc (dissoc :topic) (assoc :untopic? true))
-              :set-superseded   (cond-> acc
-                                  :always           (assoc :superseded-by target-message-id)
-                                  :always           (dissoc :unsuperseded-by? :unsuperseded-by-mid))
-              :unset-superseded (cond-> acc
-                                  :always           (dissoc :superseded-by)
-                                  :always           (assoc :unsuperseded-by? true)
-                                  target-message-id (assoc :unsuperseded-by-mid target-message-id))
-              :set-supersedes   (cond-> acc
-                                  :always           (assoc :supersedes target-message-id)
-                                  :always           (dissoc :unsupersedes? :unsupersedes-mid))
-              :unset-supersedes (cond-> acc
-                                  :always           (dissoc :supersedes)
-                                  :always           (assoc :unsupersedes? true)
-                                  target-message-id (assoc :unsupersedes-mid target-message-id))
-              :set-duplicate    (cond-> acc
-                                  :always           (assoc :duplicate-of target-message-id)
-                                  :always           (dissoc :unduplicate-of? :unduplicate-of-mid))
-              :unset-duplicate  (cond-> acc
-                                  :always           (dissoc :duplicate-of)
-                                  :always           (assoc :unduplicate-of? true)
-                                  target-message-id (assoc :unduplicate-of-mid target-message-id))
+              ;; All relation actions carry a mid (the `:param :message-id`
+              ;; in the registry guarantees the parser captured one).
+              :set-superseded   (-> acc (assoc  :superseded-by target-message-id)
+                                       (dissoc :unsuperseded-by? :unsuperseded-by-mid))
+              :unset-superseded (-> acc (dissoc :superseded-by)
+                                       (assoc  :unsuperseded-by? true
+                                               :unsuperseded-by-mid target-message-id))
+              :set-supersedes   (-> acc (assoc  :supersedes target-message-id)
+                                       (dissoc :unsupersedes? :unsupersedes-mid))
+              :unset-supersedes (-> acc (dissoc :supersedes)
+                                       (assoc  :unsupersedes? true
+                                               :unsupersedes-mid target-message-id))
+              :set-duplicate    (-> acc (assoc  :duplicate-of target-message-id)
+                                       (dissoc :unduplicate-of? :unduplicate-of-mid))
+              :unset-duplicate  (-> acc (dissoc :duplicate-of)
+                                       (assoc  :unduplicate-of? true
+                                               :unduplicate-of-mid target-message-id))
               :set-related      (-> acc
                                     (update :related-to-set   (fnil conj #{}) target-message-id)
                                     (update :related-to-unset (fnil disj #{}) target-message-id))
@@ -524,22 +520,25 @@
                 supersedes    unsupersedes?    unsupersedes-mid
                 duplicate-of  unduplicate-of?  unduplicate-of-mid
                 related-to-set related-to-unset]} resolved]
-    (str/join ", " (concat (map (fn [[attr addr]] (str (name attr) " -> " addr)) set)
-                           (map #(str "un-" (name %)) unset)
-                           (when deadline [(str "deadline " deadline)])
-                           (when undeadline? ["no deadline"])
-                           (when expiry [(str "expiry " expiry)])
-                           (when unexpiry? ["no expiry"])
-                           (when topic [(str "topic:" topic)])
-                           (when untopic? ["no topic"])
-                           (when superseded-by [(str "superseded-by:" superseded-by)])
-                           (when unsuperseded-by? [(str "not superseded-by:" unsuperseded-by-mid)])
-                           (when supersedes [(str "supersedes:" supersedes)])
-                           (when unsupersedes? [(str "not supersedes:" unsupersedes-mid)])
-                           (when duplicate-of [(str "duplicate-of:" duplicate-of)])
-                           (when unduplicate-of? [(str "not duplicate-of:" unduplicate-of-mid)])
-                           (map #(str "related-to:" %) related-to-set)
-                           (map #(str "not-related-to:" %) related-to-unset)))))
+    (str/join
+     ", "
+     (concat (map (fn [[attr addr]] (str (name attr) " -> " addr)) set)
+             (map #(str "un-" (name %)) unset)
+             (keep identity
+                   [(when deadline         (str "deadline " deadline))
+                    (when undeadline?      "no deadline")
+                    (when expiry           (str "expiry " expiry))
+                    (when unexpiry?        "no expiry")
+                    (when topic            (str "topic:" topic))
+                    (when untopic?         "no topic")
+                    (when superseded-by    (str "superseded-by:" superseded-by))
+                    (when unsuperseded-by? (str "not superseded-by:" unsuperseded-by-mid))
+                    (when supersedes       (str "supersedes:" supersedes))
+                    (when unsupersedes?    (str "not supersedes:" unsupersedes-mid))
+                    (when duplicate-of     (str "duplicate-of:" duplicate-of))
+                    (when unduplicate-of?  (str "not duplicate-of:" unduplicate-of-mid))])
+             (map #(str "related-to:" %) related-to-set)
+             (map #(str "not-related-to:" %) related-to-unset)))))
 
 (defn- setter-address
   "Return the address credited as the setter of `attr` on `current`.
@@ -847,24 +846,29 @@
                       surfaced in the pull map so `scope-permits?` can
                       resolve :setter-or-maintainer on the unset
                       command in the open-report path."
+  ;; :setter-attr must be UNIQUE per row.  Both :supersedes rows share
+  ;; the `:rel/supersedes` schema kind; if we reused `:rel/supersedes`
+  ;; as the pull-map key, `relation-setters-as-pull` would overwrite
+  ;; the from-setter with the to-setter on a chained report (one that
+  ;; supersedes X AND is superseded by Y), so the scope check on the
+  ;; `Not superseded-by:` unset would see the wrong setter.  The
+  ;; suffix `-from` / `-to` records the row's role.  These keys are
+  ;; internal to the pull map; nothing else reads them as schema attrs.
   [{:id :superseded-by :kind :supersedes :role :current-as-from
     :propagate :superseded :propagate-tgt true
     :syntax "Superseded-by"
     :mid-key :superseded-by :unset-key :unsuperseded-by? :unset-mid-key :unsuperseded-by-mid
-    :unset-syntax "Not superseded-by"
-    :setter-attr :rel/supersedes}
+    :setter-attr :rel/supersedes-from}
    {:id :supersedes :kind :supersedes :role :current-as-to
     :propagate :superseded :propagate-tgt true
     :syntax "Supersedes"
     :mid-key :supersedes :unset-key :unsupersedes? :unset-mid-key :unsupersedes-mid
-    :unset-syntax "Not supersedes"
-    :setter-attr :rel/supersedes}
+    :setter-attr :rel/supersedes-to}
    {:id :duplicate-of :kind :duplicates :role :current-as-from
     :propagate :canceled :propagate-tgt false
     :syntax "Duplicate-of"
     :mid-key :duplicate-of :unset-key :unduplicate-of? :unset-mid-key :unduplicate-of-mid
-    :unset-syntax "Not duplicate-of"
-    :setter-attr :rel/duplicates}])
+    :setter-attr :rel/duplicates-from}])
 
 (defn- compute-closure-rows
   "Enrich `closure-relation-rows` with per-row decisions derived from
@@ -1020,7 +1024,7 @@
   (into []
         (comp (filter #(= :current-as-from (:role %)))
               (map #(select-keys % [:id :kind :role :unset-key :unset-mid-key
-                                    :unset-syntax :setter-attr])))
+                                    :setter-attr])))
         closure-relation-rows))
 
 (defn- try-unclosed!
@@ -1231,15 +1235,15 @@
         word-result   (cond-> (merge implicit body-words)
                         self-ack? (dissoc :report/acked)
                         :always   (filter-words-by-scope overrides is-maint? fail-ctx))
-        line-id-ok?   (cond
-                        carrier-only? carrier-eligible-ids
-                        no-carrier?   (complement carrier-eligible-ids)
-                        :else         (constantly true))
+        keep-line?    (case line-filter
+                        :carrier-only #(contains? carrier-eligible-ids (:id %))
+                        :no-carrier   #(not (contains? carrier-eligible-ids (:id %)))
+                        (constantly true))
         lines         (when body-text
                         (->> (detect-lines report-type body-text overrides
                                            (:email/date-sent email)
                                            (:line-patterns src-cmds))
-                             (filter #(line-id-ok? (:id %)))
+                             (filter keep-line?)
                              (remove (fn [d]
                                        (and (= :set (:action d))
                                             (= :report/acked (:attr d))

src/bark/commands/registry.clj

@@ -57,13 +57,18 @@
     :syntax "Not closed"}
    ;; Closure relations -- backed by :rel/supersedes / :rel/duplicates;
    ;; :attr kept for registry shape.
-   {:id :superseded-by    :kind :trigger :action :set-superseded   :attr :rel/supersedes :scope :user
+   ;; The relation unsets use a direction-suffixed :attr so that
+   ;; `scope-permits?` finds the right setter in the pull map built
+   ;; by `relation-setters-as-pull` -- a chained report shares the
+   ;; `:rel/supersedes` schema kind across both directions, so the
+   ;; pull-map key must distinguish them.
+   {:id :superseded-by    :kind :trigger :action :set-superseded   :attr :rel/supersedes      :scope :user
     :syntax "Superseded-by"     :param :message-id :report-types #{:bug :patch :request}}
-   {:id :unsuperseded-by  :kind :trigger :action :unset-superseded :attr :rel/supersedes :scope :setter-or-maintainer
+   {:id :unsuperseded-by  :kind :trigger :action :unset-superseded :attr :rel/supersedes-from :scope :setter-or-maintainer
     :syntax "Not superseded-by" :param :message-id :report-types #{:bug :patch :request}}
-   {:id :duplicate-of    :kind :trigger :action :set-duplicate   :attr :rel/duplicates :scope :user
+   {:id :duplicate-of    :kind :trigger :action :set-duplicate   :attr :rel/duplicates      :scope :user
     :syntax "Duplicate-of"     :param :message-id :report-types #{:bug :patch :request}}
-   {:id :unduplicate-of  :kind :trigger :action :unset-duplicate :attr :rel/duplicates :scope :setter-or-maintainer
+   {:id :unduplicate-of  :kind :trigger :action :unset-duplicate :attr :rel/duplicates-from :scope :setter-or-maintainer
     :syntax "Not duplicate-of" :param :message-id :report-types #{:bug :patch :request}}
 
    ;; --- Annotations: property-set -------------------------------------------
@@ -90,9 +95,9 @@
     :syntax "No topic"}
    ;; Supersedes -- inverse role of Superseded-by (posed on the replacement;
    ;; current = :rel/to, target = :rel/from = the closed report).
-   {:id :supersedes   :kind :annotation :action :set-supersedes   :attr :rel/supersedes :scope :user
+   {:id :supersedes   :kind :annotation :action :set-supersedes   :attr :rel/supersedes    :scope :user
     :syntax "Supersedes"     :param :message-id :report-types #{:bug :patch :request}}
-   {:id :unsupersedes :kind :annotation :action :unset-supersedes :attr :rel/supersedes :scope :setter-or-maintainer
+   {:id :unsupersedes :kind :annotation :action :unset-supersedes :attr :rel/supersedes-to :scope :setter-or-maintainer
     :syntax "Not supersedes" :param :message-id :report-types #{:bug :patch :request}}
    ;; Related-to -- neutral cross-reference (no closure, multi-target,
    ;; symmetric canonicalised by :rel/id).  Multi-target makes a clean
@@ -106,11 +111,11 @@
 ;; Derived indexes
 ;; ---------------------------------------------------------------------------
 
-;; Semantic groupings
-(def trigger-commands    (filterv #(= :trigger    (:kind %)) commands))
-(def annotation-commands (filterv #(= :annotation (:kind %)) commands))
-
-;; Syntactic groupings (derived from :words vs :syntax presence)
+;; Syntactic groupings (derived from :words vs :syntax presence).
+;; The semantic axis (`:kind :trigger` / `:annotation`) is metadata
+;; on each entry, not surfaced as a derived index -- nothing consumes
+;; the full lists today; if you need them, write the `filterv` at
+;; the call site.
 (def word-commands (filterv :words  commands))
 (def line-commands (filterv :syntax commands))