From e179a1022319ec77d936f1cee21c471ac34f4d53 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Wed, 13 May 2026 16:11:16 -0500
Subject: feat(setup): scripts/setup-telega.sh prepares the docker environment
 for telega

Verifies docker is installed and the daemon is reachable, then either pulls a public image (when `TELEGA_DOCKER_IMAGE` is set) or announces the in-Emacs build path (`M-x telega-server-build`) for the user to run once. Telegram auth (phone + verification code) is interactive on first `M-x telega` and not scripted here.

Same shape as setup-email.sh: helpers are sourceable for bats, `main` runs only under direct execution. 7 bats tests stub `docker` and `command` so the suite never talks to the real daemon.
---
 scripts/setup-telega.sh      | 80 ++++++++++++++++++++++++++++++++++++++++
 tests/test-setup-telega.bats | 87 ++++++++++++++++++++++++++++++++++++++++++++
 todo.org                     | 21 +++++++----
 3 files changed, 180 insertions(+), 8 deletions(-)
 create mode 100755 scripts/setup-telega.sh
 create mode 100644 tests/test-setup-telega.bats

diff --git a/scripts/setup-telega.sh b/scripts/setup-telega.sh
new file mode 100755
index 00000000..2b565e99
--- /dev/null
+++ b/scripts/setup-telega.sh
@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Craig Jennings <c@cjennings.net>
+#
+# Prepares the docker environment telega.el uses for TDLib.
+#
+# Sequence:
+# - Verifies docker is installed and the daemon is responsive.
+# - Verifies the user can talk to docker without sudo (group membership).
+# - Pulls the telega-server image if a public one is configured (env var
+#   `TELEGA_DOCKER_IMAGE'); otherwise prints the in-Emacs build command
+#   (`M-x telega-server-build') for the user to run once.
+#
+# Does NOT handle Telegram account auth -- phone number + verification
+# code is interactive and runs inside `M-x telega' on first launch.
+#
+# Sourceable: only `main' runs when the script is executed directly, so
+# the helpers can be tested with bats.
+
+set -euo pipefail
+
+# Public image override.  When set, the script pulls this image directly
+# instead of falling back to the in-Emacs build flow.  Default empty so
+# the script doesn't assume an image name that may or may not exist
+# upstream.
+: "${TELEGA_DOCKER_IMAGE:=}"
+
+ensure_docker_installed() {
+    if ! command -v docker >/dev/null 2>&1; then
+        echo "  ✗ docker not found on PATH"
+        echo "    install docker (https://docs.docker.com/get-docker/) and rerun"
+        return 1
+    fi
+    echo "  ✓ docker present: $(command -v docker)"
+}
+
+ensure_docker_running() {
+    if ! docker info >/dev/null 2>&1; then
+        echo "  ✗ cannot talk to the docker daemon"
+        echo "    start the daemon (e.g. 'sudo systemctl start docker') or"
+        echo "    add your user to the 'docker' group, then re-login and rerun"
+        return 1
+    fi
+    echo "  ✓ docker daemon reachable"
+}
+
+pull_or_announce_image() {
+    if [[ -z "$TELEGA_DOCKER_IMAGE" ]]; then
+        cat <<EOF
+  → no public image configured (set TELEGA_DOCKER_IMAGE to override)
+    build the telega-server image once from inside Emacs:
+      M-x telega-server-build
+    telega.el handles the docker build under the hood when
+    \`telega-use-docker' is t (set in modules/telega-config.el).
+EOF
+        return 0
+    fi
+    echo "  → pulling $TELEGA_DOCKER_IMAGE..."
+    if docker pull "$TELEGA_DOCKER_IMAGE"; then
+        echo "  ✓ pulled $TELEGA_DOCKER_IMAGE"
+    else
+        echo "  ✗ pull failed for $TELEGA_DOCKER_IMAGE"
+        return 1
+    fi
+}
+
+main() {
+    echo "→ checking docker..."
+    ensure_docker_installed
+    ensure_docker_running
+    echo "→ preparing telega-server image..."
+    pull_or_announce_image
+    echo "✅ Telega docker setup complete."
+    echo "   First launch: M-x telega -- enter phone + verification code interactively."
+}
+
+# Run main only when the script is executed directly.  Sourcing this file
+# (for example from a bats test) just defines the helpers above.
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi
diff --git a/tests/test-setup-telega.bats b/tests/test-setup-telega.bats
new file mode 100644
index 00000000..7935ea4a
--- /dev/null
+++ b/tests/test-setup-telega.bats
@@ -0,0 +1,87 @@
+#!/usr/bin/env bats
+# Tests for the helpers in scripts/setup-telega.sh.
+#
+# Sources the script (so only the helpers come in -- `main' runs only
+# when the script is executed directly) and stubs `docker' / `command'
+# in each test so nothing actually talks to the docker daemon or
+# requires a real telega-server image.
+
+setup() {
+    source "${BATS_TEST_DIRNAME}/../scripts/setup-telega.sh"
+}
+
+# --------------------------- ensure_docker_installed ----------------------
+
+@test "ensure_docker_installed: succeeds when docker is on PATH" {
+    command() {
+        if [[ "$1" == "-v" && "$2" == "docker" ]]; then
+            echo "/usr/bin/docker"
+            return 0
+        fi
+        builtin command "$@"
+    }
+    run ensure_docker_installed
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"docker present"* ]]
+}
+
+@test "ensure_docker_installed: fails when docker is missing" {
+    command() {
+        if [[ "$1" == "-v" && "$2" == "docker" ]]; then
+            return 1
+        fi
+        builtin command "$@"
+    }
+    run ensure_docker_installed
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"docker not found"* ]]
+    [[ "$output" == *"get-docker"* ]]
+}
+
+# --------------------------- ensure_docker_running ------------------------
+
+@test "ensure_docker_running: succeeds when 'docker info' exits 0" {
+    docker() { return 0; }
+    run ensure_docker_running
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"reachable"* ]]
+}
+
+@test "ensure_docker_running: fails when 'docker info' errors" {
+    docker() { return 1; }
+    run ensure_docker_running
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"cannot talk"* ]]
+    [[ "$output" == *"docker group"* || "$output" == *"systemctl"* ]]
+}
+
+# --------------------------- pull_or_announce_image -----------------------
+
+@test "pull_or_announce_image: announces the in-Emacs build when no image is set" {
+    TELEGA_DOCKER_IMAGE=""
+    run pull_or_announce_image
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"M-x telega-server-build"* ]]
+}
+
+@test "pull_or_announce_image: pulls when TELEGA_DOCKER_IMAGE is set" {
+    TELEGA_DOCKER_IMAGE="example/telega:1"
+    docker() {
+        if [[ "$1" == "pull" ]]; then
+            echo "pulling $2"
+            return 0
+        fi
+        return 1
+    }
+    run pull_or_announce_image
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"pulled example/telega:1"* ]]
+}
+
+@test "pull_or_announce_image: fails when 'docker pull' errors" {
+    TELEGA_DOCKER_IMAGE="example/telega:1"
+    docker() { return 1; }
+    run pull_or_announce_image
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"pull failed"* ]]
+}
diff --git a/todo.org b/todo.org
index 77a0fe0e..78eb448b 100644
--- a/todo.org
+++ b/todo.org
@@ -39,20 +39,25 @@ Tags are additive. For example, a small wrong-behavior fix can be
 
 * Emacs Open Work
 
-** TODO [#A] Add Telegram Messaging
+** DONE [#A] Add Telegram Messaging
 https://github.com/zevlg/telega.el
 Make sure there is a setup script to run, so that the docker container can be installed post emacs dotfiles repository clone on a fresh install
 also, let's add an icon to the dashboard for this. perhaps this is the beginning of the third row? If so, add a child task to review and balance the dashboard icons
 
-Progress so far:
-- =modules/telega-config.el= shipped with =telega-use-docker t= and the
-  =C-; G= launcher binding (=C-; t= and =C-; m t= were both taken).
+Shipped this session:
+- =modules/telega-config.el= -- =use-package telega= with
+  =telega-use-docker t=; launcher on =C-; G= (=C-; t= and =C-; m t=
+  were both taken).
 - Dashboard Row 3 added with the Telegram icon; dashboard-mode-map =g=
   key launches =telega=.
-- TDLib docker setup script (=scripts/setup-telega.sh=) still TODO --
-  see child task below.
-
-*** TODO [#B] Add =scripts/setup-telega.sh= for TDLib docker container :feature:
+- =scripts/setup-telega.sh= -- verifies docker presence + daemon
+  reachability; pulls =$TELEGA_DOCKER_IMAGE= when set, otherwise
+  announces =M-x telega-server-build= for the in-Emacs build path.
+  7 bats tests in =tests/test-setup-telega.bats= (docker stubbed).
+- Auth (phone + verification code) is interactive on first =M-x telega=
+  -- not scripted.
+
+*** DONE [#B] Add =scripts/setup-telega.sh= for TDLib docker container :feature:
 Pull or build the telega TDLib container so a fresh-clone install can
 run telega without a system-wide TDLib build.  Mirror the
 =scripts/setup-email.sh= pattern: =main()= wrapped in a
-- 
cgit v1.2.3