Merge pull request 'Fix issues #1, #3, #5: misc improvements' (#6) from fix/issues-1-3-5-misc-improvements into master

Reviewed-on: #6

DESCRIPTION

@@ -19,6 +19,7 @@ Depends:
 Imports:
     ggplot2 (>= 4.0.0),
     jpeg,
+    jsonlite,
     png,
     stringr,
     gridExtra,

NAMESPACE

@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+export(beep)
 export(add_logo)
 export(add_logo_ga)
 export(agresti_coull_interval)
@@ -71,3 +72,4 @@ importFrom(stats,qnorm)
 importFrom(stats,runif)
 importFrom(stringdist,stringsim)
 importFrom(stringr,str_count)
+importFrom(utils,flush.console)

R/notifications.R

@@ -0,0 +1,153 @@
+#' Send a CLI beep / desktop notification
+#'
+#' Plays an audible beep in the terminal and/or sends a desktop notification
+#' when a long-running R script completes or reaches a milestone.
+#'
+#' @param msg Character. Optional message to include in the notification.
+#'   When `type = "notify"`, this becomes the notification body.
+#' @param type Character. Notification method:
+#'   - `"beep"` (default): emit a terminal bell character (`\007`).
+#'     Works in any terminal that supports the bell.
+#'   - `"notify"`: send a desktop notification via `notify-send` (Linux) or
+#'     `osascript` (macOS). Falls back to `"beep"` if neither tool is found.
+#'   - `"webhook"`: POST a JSON payload to a URL. Requires `url` argument.
+#'   - `"all"`: play beep + send desktop notification (webhook only if `url`
+#'     is provided).
+#' @param url Character. Webhook URL for `type = "webhook"` or `"all"`.
+#'   A JSON payload is POSTed with keys `message`, `status`, and `timestamp`.
+#' @param status Character. Status label for the notification (default `"done"`).
+#'   Used in the notification title and webhook payload.
+#' @param timeout Numeric. Seconds to wait for the webhook POST to complete
+#'   (default `5`). Ignored for non-webhook types.
+#' @param quiet Logical. If `TRUE`, suppress the terminal beep even when
+#'   `type` includes `"beep"`. Useful for silent background runs.
+#'
+#' @return Invisible `NULL`.
+#'
+#' @section Requirements:
+#' - `type = "notify"` requires `notify-send` (Linux) or `osascript` (macOS).
+#' - `type = "webhook"` requires network access to the provided URL.
+#'
+#' @section Examples:
+#' \preformatted{
+#' # Simple terminal beep
+#' beep()
+#'
+#' # Desktop notification with message
+#' beep("Analysis complete!", type = "notify")
+#'
+#' # Send to a webhook (e.g., Slack, Discord, custom endpoint)
+#' beep("Job finished", type = "webhook",
+#'      url = "https://hooks.slack.com/services/...")
+#'
+#' # Beep + desktop notification
+#' beep("Processing done", type = "all")
+#' }
+#'
+#' @export
+#'
+beep <- function(msg = "done",
+                 type = c("beep", "notify", "webhook", "all"),
+                 url = NULL,
+                 status = "done",
+                 timeout = 5,
+                 quiet = FALSE) {
+  type <- match.arg(type)
+
+  # -- Terminal beep ----------------------------------------------------------
+  if (!quiet && grepl("beep", type)) {
+    cat("\007")
+    flush.console()
+  }
+
+  # -- Desktop notification ---------------------------------------------------
+  if (grepl("notify", type)) {
+    .send_desktop_notify(msg, status)
+  }
+
+  # -- Webhook ----------------------------------------------------------------
+  if (grepl("webhook", type) && !is.null(url)) {
+    .send_webhook(url, msg, status, timeout)
+  }
+
+  invisible(NULL)
+}
+
+
+# -- Internal helpers ---------------------------------------------------------
+
+#' Send a desktop notification via notify-send or osascript
+#'
+#' @param msg Message body
+#' @param status Status label for the title
+#' @keywords internal
+.send_desktop_notify <- function(msg, status) {
+  # Linux: notify-send
+  if (.has_command("notify-send")) {
+    system2("notify-send", args = c(status, msg),
+            stdout = TRUE, stderr = TRUE)
+    return(invisible(NULL))
+  }
+
+  # macOS: osascript
+  if (.has_command("osascript")) {
+    system2("osascript",
+            args = c("-e",
+                     paste0("display notification \"", msg,
+                            "\" with title \"", status, "\"")),
+            stdout = TRUE, stderr = TRUE)
+    return(invisible(NULL))
+  }
+
+  # Neither tool available — silently skip
+  invisible(NULL)
+}
+
+
+#' POST a JSON payload to a webhook URL
+#'
+#' @param url Webhook URL
+#' @param msg Message body
+#' @param status Status label
+#' @param timeout Seconds to wait for the request
+#' @keywords internal
+.send_webhook <- function(url, msg, status, timeout) {
+  payload <- jsonlite::toJSON(list(
+    message   = msg,
+    status    = status,
+    timestamp = format(Sys.time(), "%Y-%m-%dT%H:%M:%S%z")
+  ), auto_unbox = TRUE)
+
+  # Use curl via system2() for maximum compatibility (no extra R deps).
+  # system2() passes arguments directly to the executable without shell
+  # interpolation, avoiding command injection.
+  if (.has_command("curl")) {
+    system2("curl",
+            args = c("-s", "-X", "POST",
+                     "-H", "Content-Type: application/json",
+                     "-d", payload,
+                     url,
+                     "--max-time", as.character(timeout)),
+            stdout = TRUE, stderr = TRUE)
+  } else if (.has_command("wget")) {
+    system2("wget",
+            args = c("-q", "-O", "/dev/null",
+                     paste0("--post-data=", payload),
+                     paste0("--header=Content-Type: application/json"),
+                     paste0("--timeout=", timeout),
+                     url),
+            stdout = TRUE, stderr = TRUE)
+  }
+
+  invisible(NULL)
+}
+
+
+#' Check if a command exists on the system PATH
+#'
+#' @param cmd Command name
+#' @return Logical
+#' @keywords internal
+.has_command <- function(cmd) {
+  Sys.which(cmd) != ""
+}

R/utils.R

@@ -149,6 +149,9 @@ race_short_names <- function(x) {
 #' Sum a numeric that contains missing values and ignore missing values
 #'
 #' @param x a numeric vector
+#' @param quiet Logical. If `TRUE` (default `FALSE`), suppress the warning
+#'   message. Useful when calling `na_sum()` inside a loop or `dplyr` pipeline
+#'   where the message would be emitted repeatedly.
 #'
 #' @return the sum, ignoring any missing values
 #' @export
@@ -156,9 +159,12 @@ race_short_names <- function(x) {
 #' @examples
 #' x <- c(2, NA, 4, 9)
 #' na_sum(x) # 15
-na_sum <- function(x) {
+#' na_sum(x, quiet = TRUE) # 15 (no message)
+na_sum <- function(x, quiet = FALSE) {
   stopifnot(is.numeric(x))
+  if (!quiet) {
     message("Taking a sum with missing values equal to 0, be careful!")
+  }
   x <- na_zero(x)
   return(sum(x))
 }

inst/quarto/_brand.yml

@@ -2,17 +2,16 @@
 # Optional but recommended — Quarto auto-applies these to HTML, PDF, and Revealjs.
 # https://quarto.org/docs/authoring/brand.html
 
-brand:
-  meta:
+meta:
   name: Civilytics Consulting
   description: Turning public data into clear, actionable analysis for public good.
 
-  logo:
+logo:
   small: assets/logo/civilytics-mark.svg
   medium: assets/logo/civilytics-wordmark.svg
   large: assets/logo/civilytics-wordmark.svg
 
-  color:
+color:
   palette:
     paper:    "#FAF7F2"
     paper-2:  "#F2EDE4"
@@ -38,7 +37,7 @@ brand:
   dark:      ink
   link:      navy
 
-  typography:
+typography:
   fonts:
     - family: "Source Serif 4"
       source: google

man/beep.Rd

@@ -0,0 +1,71 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/notifications.R
+\name{beep}
+\alias{beep}
+\title{Send a CLI beep / desktop notification}
+\usage{
+beep(
+  msg = "done",
+  type = c("beep", "notify", "webhook", "all"),
+  url = NULL,
+  status = "done",
+  timeout = 5,
+  quiet = FALSE
+)
+}
+\arguments{
+\item{msg}{Character. Optional message to include in the notification.
+When \code{type = "notify"}, this becomes the notification body.}
+
+\item{type}{Character. Notification method:
+\itemize{
+\item \code{"beep"} (default): emit a terminal bell character.
+Works in any terminal that supports the bell.
+\item \code{"notify"}: send a desktop notification via \code{notify-send} (Linux) or
+\code{osascript} (macOS). Falls back to \code{"beep"} if neither tool is found.
+\item \code{"webhook"}: POST a JSON payload to a URL. Requires \code{url} argument.
+\item \code{"all"}: play beep + send desktop notification (webhook only if \code{url}
+is provided).
+}}
+
+\item{url}{Character. Webhook URL for \code{type = "webhook"} or \code{"all"}.
+A JSON payload is POSTed with keys \code{message}, \code{status}, and \code{timestamp}.}
+
+\item{status}{Character. Status label for the notification (default \code{"done"}).
+Used in the notification title and webhook payload.}
+
+\item{timeout}{Numeric. Seconds to wait for the webhook POST to complete
+(default \code{5}). Ignored for non-webhook types.}
+
+\item{quiet}{Logical. If \code{TRUE}, suppress the terminal beep even when
+\code{type} includes \code{"beep"}. Useful for silent background runs.}
+}
+\value{
+Invisible \code{NULL}.
+}
+\description{
+Plays an audible beep in the terminal and/or sends a desktop notification
+when a long-running R script completes or reaches a milestone.
+}
+\section{Requirements}{
+\itemize{
+\item \code{type = "notify"} requires \code{notify-send} (Linux) or \code{osascript} (macOS).
+\item \code{type = "webhook"} requires network access to the provided URL.
+}
+}
+\section{Examples}{
+\preformatted{
+# Simple terminal beep
+beep()
+
+# Desktop notification with message
+beep("Analysis complete!", type = "notify")
+
+# Send to a webhook (e.g., Slack, Discord, custom endpoint)
+beep("Job finished", type = "webhook",
+     url = "https://hooks.slack.com/services/...")
+
+# Beep + desktop notification
+beep("Processing done", type = "all")
+}
+}

man/na_sum.Rd

@@ -4,10 +4,14 @@
 \alias{na_sum}
 \title{Sum a numeric that contains missing values and ignore missing values}
 \usage{
-na_sum(x)
+na_sum(x, quiet = FALSE)
 }
 \arguments{
 \item{x}{a numeric vector}
+
+\item{quiet}{Logical. If \code{TRUE} (default \code{FALSE}), suppress the warning
+message. Useful when calling \code{na_sum()} inside a loop or \code{dplyr} pipeline
+where the message would be emitted repeatedly.}
 }
 \value{
 the sum, ignoring any missing values
@@ -18,4 +22,5 @@ Sum a numeric that contains missing values and ignore missing values
 \examples{
 x <- c(2, NA, 4, 9)
 na_sum(x) # 15
+na_sum(x, quiet = TRUE) # 15 (no message)
 }

tests/testthat/test_notifications.R

@@ -0,0 +1,56 @@
+# Test beep / notification function
+
+context("Test beep() function")
+
+test_that("beep() returns invisibly", {
+  expect_invisible(beep())
+  expect_invisible(beep("test", type = "beep"))
+  expect_invisible(beep("test", type = "all"))
+})
+
+test_that("beep() with quiet=TRUE produces no output", {
+  expect_silent(beep("test", type = "beep", quiet = TRUE))
+})
+
+test_that("beep() with type=notify is silent when no tools available", {
+  # When notify-send and osascript are both absent, should be silent
+  expect_silent(beep("test", type = "notify"))
+})
+
+test_that("beep() with type=webhook and no URL is silent", {
+  expect_silent(beep("test", type = "webhook"))
+})
+
+test_that("beep(type='all') exercises both beep and notify paths", {
+  # type="all" should trigger the terminal beep (unless quiet) and
+  # attempt a desktop notification. We verify by checking that the
+  # function returns invisibly and does not error when notify-send
+  # is absent (which is the case in CI).
+  expect_invisible(beep("all-test", type = "all"))
+  expect_invisible(beep("all-test", type = "all", quiet = TRUE))
+})
+
+test_that("notification helpers use system2() to prevent command injection", {
+  # Security regression: .send_webhook and .send_desktop_notify must
+  # use system2() with separate args, never system() with shell
+  # interpolation.  system2() passes arguments directly to the
+  # executable without going through a shell, so shell metacharacters
+  # in msg, status, url, or payload are treated as literal data.
+
+  webhook_body <- deparse(body(.send_webhook))
+  notify_body  <- deparse(body(.send_desktop_notify))
+
+  # Must use system2
+  expect_true(any(grepl("system2", webhook_body)),
+              info = ".send_webhook() must use system2() to avoid shell injection")
+  expect_true(any(grepl("system2", notify_body)),
+              info = ".send_desktop_notify() must use system2() to avoid shell injection")
+
+  # Must NOT use system( with string interpolation (system("curl ..."))
+  # We look for system( followed by a string literal (the old pattern).
+  # system2 calls look like system2("curl", args = ...) which is fine.
+  expect_false(any(grepl('system\\(\\s*"', webhook_body)),
+               info = ".send_webhook() must not use system() with interpolated strings")
+  expect_false(any(grepl('system\\(\\s*"', notify_body)),
+               info = ".send_desktop_notify() must not use system() with interpolated strings")
+})

tests/testthat/test_utils.R

@@ -58,6 +58,12 @@ test_that("na_sum fails with non-numerics", {
   expect_error(na_sum(as.factor(1:10)))
 })
 
+test_that("na_sum quiet=TRUE suppresses the message", {
+  expect_message(na_sum(c(1:10, NA)), "Taking a sum")
+  expect_silent(na_sum(c(1:10, NA), quiet = TRUE))
+  expect_equal(na_sum(c(1:10, NA), quiet = TRUE), 55)
+})
+
 
 context("Test Utilities - Pretty Count")