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.

2 files changed, 167 insertions, 0 deletions

diff --git a/scripts/setup-telega.sh b/scripts/setup-telega.sh
new file mode 100755
index 000000000..2b565e997
--- /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 000000000..7935ea4ab
--- /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"* ]]
+}