aboutsummaryrefslogtreecommitdiff
path: root/archive
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-11-20 15:59:47 -0600
committerCraig Jennings <c@cjennings.net>2026-11-20 15:59:47 -0600
commit4df81e5e751cf50c45e1b82e694394ddcb133ada (patch)
tree269e7d0dc65bf71965adc73c55858b2b7ae2f068 /archive
parent1e679c7193f55950849cf9b9d9ac41108db26b3f (diff)
downloaddotemacs-4df81e5e751cf50c45e1b82e694394ddcb133ada.tar.gz
dotemacs-4df81e5e751cf50c45e1b82e694394ddcb133ada.zip
refactor(telega): retire the Telegram client to the archive
I stopped using Telegram in Emacs, so the client goes to the archive. - The module and its tests moved to archive/. - The setup script and docker build files moved with them. - I dropped the init.el require and the make telega-image target. - The dashboard loses its Telegram launcher. Rows are now 5 4 2 2. - C-; T is free again.
Diffstat (limited to 'archive')
-rw-r--r--archive/README.org13
-rw-r--r--archive/docker/telega-server/Dockerfile16
-rw-r--r--archive/modules/telega-config.el235
-rwxr-xr-xarchive/scripts/setup-telega.sh119
-rw-r--r--archive/tests/test-setup-telega.bats134
-rw-r--r--archive/tests/test-telega-config--docker-pin.el212
-rw-r--r--archive/tests/test-telega-config--server-death.el131
-rw-r--r--archive/tests/test-telega-config.el58
8 files changed, 918 insertions, 0 deletions
diff --git a/archive/README.org b/archive/README.org
index e292065a..4703fbe5 100644
--- a/archive/README.org
+++ b/archive/README.org
@@ -33,6 +33,8 @@ Retired files keep their origin directory so a restore is a straight move back:
- =archive/custom/= — retired vendored third-party files
- =archive/tests/= — tests belonging to retired modules
- =archive/gptel/= — the gptel feature subtree, retired as a unit
+- =archive/scripts/= — setup scripts that served a retired module
+- =archive/docker/= — container build files that served a retired module
* Inventory
@@ -53,6 +55,17 @@ Retired files keep their origin directory so a restore is a straight move back:
files moved to =archive/tests/= with it (=test-signal-config*.el=,
=test-signel-*.el=). The spec record is
=docs/specs/signal-client-spec.org= (IMPLEMENTED, then retired).
+- =telega-config.el= — the Telegram client (telega.el with TDLib in a pinned
+ docker image), retired whole on 2026-11-20 because I'd stopped using it. Its
+ three ERT files and the bats suite for the setup script moved to
+ =archive/tests/=. The pieces that only existed to serve it moved too:
+ =archive/scripts/setup-telega.sh= and =archive/docker/telega-server/=. The
+ =make telega-image= target was deleted, so a restore has to bring back that
+ target along with the files; the tag it built was
+ =cj/telega-server:1.8.66-glycin=. Retiring it freed =C-; T= and the
+ dashboard's =G= launcher. The installed =telega= package is untracked, so
+ I delete it by hand on each machine. The pin-mismatch diagnosis stays in
+ =docs/design/2026-08-23-telega-docker-pin-tdlib-mismatch.org=.
** archive/custom/
diff --git a/archive/docker/telega-server/Dockerfile b/archive/docker/telega-server/Dockerfile
new file mode 100644
index 00000000..6bd2c579
--- /dev/null
+++ b/archive/docker/telega-server/Dockerfile
@@ -0,0 +1,16 @@
+# telega-server image for modules/telega-config.el. Build with `make telega-image'.
+#
+# Upstream's zevlg/telega-server:latest ships tdlib 1.8.66 (the floor the
+# current telega package demands) but its telega-server binary fails to start:
+# libgdk_pixbuf needs libglycin-2.so.0 and the image doesn't carry it. Known
+# open bug: https://github.com/zevlg/telega.el/issues/596. This derived image
+# adds the one missing package and nothing else.
+#
+# The base is pinned by digest, not tag, so a rebuild on another machine gets
+# the same upstream layers. libglycin itself is deliberately not version
+# pinned: Alpine's repos keep only the current build of a package, so an exact
+# `libglycin=X-rN' fails the build the day it rotates, which is worse than one
+# layer differing between machines. When #596 is fixed upstream, point
+# `cj/telega-docker-image' back at a registry digest and delete this file.
+FROM zevlg/telega-server@sha256:aa7e79c4e9587c84065782df9399653fb1a967078b08ec1ded77738d4c2d70ad
+RUN apk add --no-cache libglycin
diff --git a/archive/modules/telega-config.el b/archive/modules/telega-config.el
new file mode 100644
index 00000000..b9b80481
--- /dev/null
+++ b/archive/modules/telega-config.el
@@ -0,0 +1,235 @@
+;;; telega-config.el --- Telega Telegram client config -*- lexical-binding: t; coding: utf-8; -*-
+;; author: Craig Jennings <c@cjennings.net>
+
+;;; Commentary:
+;;
+;; Layer: 4 (Optional).
+;; Category: O/D/P.
+;; Load shape: eager.
+;; Eager reason: none; optional Telegram client that registers a keymap, a
+;; command-loaded deferral candidate.
+;; Top-level side effects: registers a telega keymap under cj/custom-keymap,
+;; package config.
+;; Runtime requires: keybindings.
+;; Direct test load: yes (requires keybindings explicitly).
+;;
+;; Configures telega.el (https://github.com/zevlg/telega.el) as an
+;; in-Emacs Telegram client.
+;;
+;; TDLib (Telegram Database Library) runs in a docker container via
+;; `telega-use-docker' so a fresh-clone install does not need a
+;; system-level TDLib build. The image is built locally from
+;; =docker/telega-server/Dockerfile= with =make telega-image= (see the
+;; pin section below for why it is not pulled from the registry);
+;; =scripts/setup-telega.sh= covers the rest of a fresh clone.
+;;
+;; First-run auth (phone number + Telegram verification code) is
+;; interactive and happens inside `M-x telega'. This module does not
+;; script it.
+;;
+;; Install:
+;;
+;; M-x package-refresh-contents
+;; M-x package-install RET telega
+;;
+;; The refresh is important. MELPA rotates dated snapshot tarballs out
+;; from under the cached archive index periodically, so if the local
+;; archive-contents file points at a snapshot that no longer exists on
+;; the server the install fails with a 404. Refreshing pulls a current
+;; index. This module deliberately sets `:ensure nil' so a stale
+;; archive doesn't take Emacs init down at startup; if the package
+;; isn't installed yet, `C-; T' surfaces a clear "install telega" error
+;; until the install runs once.
+;;
+;; Launcher: =C-; T= (mnemonic: Telegram). Previously `C-; G' because
+;; `T' was contested between org-table and transcription menus -- both
+;; have been moved (org-table flattened under `C-; O', transcription
+;; cleared to M-x), so `T' is now telega's outright.
+
+;;; Code:
+
+(require 'keybindings)
+(require 'system-lib) ; cj/log-silently, used by the death alert
+
+(use-package telega
+ :defer t
+ :ensure nil
+ :commands (telega)
+ :custom
+ (telega-use-docker t)
+ :config
+ ;; Without this, incoming Telegram messages are invisible unless their
+ ;; buffer is on screen -- telega ships desktop notifications but leaves
+ ;; the mode off by default. Runs at telega load (M-x telega), respects
+ ;; telega's own per-chat mute settings. From the 2026-06 config audit;
+ ;; routing through a shared messenger notifier is the unification task.
+ (telega-notifications-mode 1))
+
+;; --------------------------- telega Docker Image Pin -------------------------
+;; telega picks its container image in `telega-docker--image-name', which only
+;; pins to a version tag when `telega-tdlib-min-version' equals
+;; `telega-tdlib-max-version' and the version ends in ".0". Here min is
+;; "1.8.66" and max is nil, so that test never passes and the image is always
+;; "zevlg/telega-server:latest" -- a floating tag. The elpa package is fixed
+;; at whatever version was installed, so the server can be replaced underneath
+;; a static elisp without anything announcing it.
+;;
+;; The pin used to be a registry digest. It became a local tag on 2026-08-25:
+;; the telega package raised its tdlib floor to 1.8.66, and upstream's only
+;; image at that version fails to start (libglycin missing,
+;; zevlg/telega.el#596). docker/telega-server/Dockerfile derives a working
+;; image from that upstream digest plus the one missing package, and
+;; `make telega-image' builds it under the tag below. The digest guarantee
+;; now lives in the Dockerfile's FROM line; the Makefile owns the tag and a
+;; test holds this default equal to it. Set to nil to hand the choice back
+;; to telega.
+
+(defcustom cj/telega-docker-image
+ "cj/telega-server:1.8.66-glycin"
+ "Container image reference for `telega-server', or nil for telega's default.
+The default names the image `make telega-image' builds locally from
+docker/telega-server/Dockerfile, whose base is pinned by upstream digest.
+It must match TELEGA_IMAGE in the Makefile; `cj/telega' refuses to launch
+when the image is not present, since docker would otherwise try to pull a
+local-only tag from the registry and fail confusingly."
+ :type '(choice (const :tag "Let telega infer the image" nil)
+ (string :tag "Image reference"))
+ :group 'telega-docker)
+
+(defun cj/--telega-docker-pinned-image ()
+ "Return the configured image pin, or nil when none is usable.
+A blank or non-string setting yields nil rather than reaching the docker
+command line, where it would fail in a way that looks unrelated to this."
+ (when (stringp cj/telega-docker-image)
+ (let ((pin (string-trim cj/telega-docker-image)))
+ (unless (string-empty-p pin) pin))))
+
+(defun cj/--telega-docker-image-name (orig-fun &rest args)
+ "Return the pinned telega-server image, else call ORIG-FUN with ARGS.
+`:around' advice on `telega-docker--image-name', so clearing the pin
+restores telega's own inference instead of breaking the image name."
+ (or (cj/--telega-docker-pinned-image)
+ (apply orig-fun args)))
+
+(with-eval-after-load 'telega-util
+ (advice-add 'telega-docker--image-name :around #'cj/--telega-docker-image-name))
+
+;; ------------------------- telega-server Death Alert -------------------------
+;; telega's own sentinel reports an abnormal server exit with `message', which
+;; scrolls out of the echo area unseen. That is how a dead server reads as a
+;; quiet Telegram: the scan stops partway and the unscanned chats look like
+;; chats with nothing in them. It has happened twice (2026-07-10, 2026-07-27),
+;; caught both times only because something downstream noticed. A desktop
+;; notification makes the death itself visible.
+
+(declare-function notifications-notify "notifications")
+
+(defun cj/--telega-server-death-p (status)
+ "Return non-nil when exit STATUS means the server died abnormally.
+Any non-zero integer counts, which covers both a non-zero exit code and a
+fatal signal number (`process-exit-status' reports SIGSEGV as 11). A
+non-integer STATUS returns nil rather than signalling: this runs inside
+telega's sentinel, where an error would abort telega's own cleanup."
+ (and (integerp status)
+ (not (zerop status))))
+
+(defun cj/--telega-server-exit-status (proc)
+ "Return PROC's exit status, or nil when it can't be determined.
+Guarded because the sentinel hands over whatever process object it has,
+and a bad one must not break telega's status handling."
+ (condition-case nil
+ (and (processp proc) (process-exit-status proc))
+ (error nil)))
+
+(defun cj/--telega-server-death-body (status event)
+ "Build the notification body for a server death with STATUS and EVENT.
+EVENT is the sentinel's event string, which carries a trailing newline that
+would render as dead space in a desktop notification."
+ (let ((detail (string-trim (or event ""))))
+ (concat (format "telega-server died (status %s). " status)
+ (unless (string-empty-p detail) (concat detail ". "))
+ "Telegram coverage is down until it restarts.")))
+
+(defun cj/--telega-server-send-notification (title body)
+ "Deliver a desktop notification with TITLE and BODY.
+Prefers the external notify script (persistent, so it waits rather than
+auto-dismissing while away), falling back to `notifications-notify'.
+Mirrors `cj/slack--send-notification'."
+ (let ((script (executable-find "notify")))
+ (if script
+ (start-process "telega-death-notify" nil script "fail" title body "--persist")
+ (unless (fboundp 'notifications-notify)
+ (require 'notifications))
+ (notifications-notify :title title :body body))))
+
+(defun cj/--telega-server-notify-death (proc event)
+ "Notify when the telega-server PROC dies abnormally. EVENT is its event string.
+Installed as `:after' advice on `telega-server--sentinel'. Silent on a
+clean exit, so quitting telega deliberately never pages.
+
+The whole body is guarded: a notifier failure here would otherwise escape
+into telega's sentinel and abort its status handling and relogin path."
+ (condition-case err
+ (let ((status (cj/--telega-server-exit-status proc)))
+ (when (cj/--telega-server-death-p status)
+ (cj/--telega-server-send-notification
+ "Telegram: telega-server died"
+ (cj/--telega-server-death-body status event))))
+ (error
+ (cj/log-silently
+ (format "telega death notify failed: %s" (error-message-string err))))))
+
+;; Named, never a lambda: anonymous advice can't be `advice-remove'd by
+;; reference, so a live daemon keeps running it after the source stops
+;; installing it.
+(with-eval-after-load 'telega-server
+ (advice-add 'telega-server--sentinel :after #'cj/--telega-server-notify-death))
+
+(defun cj/--telega-docker-image-present-p (image)
+ "Return non-nil when IMAGE exists in the local docker image store.
+Uses `docker image inspect' rather than `docker images': the listing hides
+digest-pulled and untagged images, and this check exists because that
+listing lied once. Any failure (docker absent, daemon down) reads as
+not-present, which routes the user to the same make target."
+ (condition-case nil
+ (zerop (call-process "docker" nil nil nil "image" "inspect" image))
+ (error nil)))
+
+(defun cj/--telega-missing-image-message (image)
+ "Return the user-facing message for a pinned IMAGE that is not built yet."
+ (format "telega-server image %s is not built -- run `make telega-image' in %s"
+ image (abbreviate-file-name user-emacs-directory)))
+
+(defun cj/telega ()
+ "Launch telega.el with a helpful message when it isn't installed yet.
+
+The =telega= Emacs package uses =:ensure nil= in this config so a
+stale MELPA archive index can't take startup down with a 404. The
+trade-off: a fresh clone needs a one-time install before this
+launcher works. Without this wrapper, the autoload stub fails with
+the cryptic =Cannot open load file: telega=; with it, the user gets
+pointed at =scripts/setup-telega.sh= and the manual fallback.
+
+When `cj/telega-docker-image' is set, the image must already be built:
+it is a local tag, so a missing one would send docker to the registry
+for something that was never there. The check is skipped with no pin,
+where telega infers and pulls its own image."
+ (interactive)
+ (unless (or (featurep 'telega)
+ (locate-library "telega"))
+ (user-error
+ (concat "telega not installed -- run scripts/setup-telega.sh, "
+ "or `M-x package-install RET telega'")))
+ (let ((image (cj/--telega-docker-pinned-image)))
+ (when (and image (not (cj/--telega-docker-image-present-p image)))
+ (user-error "%s" (cj/--telega-missing-image-message image))))
+ (telega))
+
+(cj/register-command "T" #'cj/telega)
+
+(with-eval-after-load 'which-key
+ (which-key-add-key-based-replacements
+ "C-; T" "telegram (telega)"))
+
+(provide 'telega-config)
+;;; telega-config.el ends here
diff --git a/archive/scripts/setup-telega.sh b/archive/scripts/setup-telega.sh
new file mode 100755
index 00000000..351f98ba
--- /dev/null
+++ b/archive/scripts/setup-telega.sh
@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# Craig Jennings <c@cjennings.net>
+#
+# Prepares everything telega.el needs on a fresh clone.
+#
+# 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 points at `make telega-image', which
+# builds the pinned image from docker/telega-server/Dockerfile.
+# - Installs the `telega' Emacs package via package.el if it isn't
+# already in package-user-dir. modules/telega-config.el uses
+# `:ensure nil' (a stale MELPA index can 404 and take startup down
+# if auto-install runs in init), so the install has to happen
+# explicitly somewhere. This is that somewhere.
+#
+# 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 the repo's Dockerfile:
+ make telega-image
+ modules/telega-config.el pins \`cj/telega-docker-image' to the tag
+ that target builds (docker/telega-server/Dockerfile).
+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
+}
+
+ensure_telega_package() {
+ if ! command -v emacs >/dev/null 2>&1; then
+ echo " ✗ emacs not on PATH; install Emacs first"
+ return 1
+ fi
+ # Probe quietly whether telega is already in package-user-dir.
+ if emacs --batch --eval "(progn
+ (require 'package)
+ (package-initialize)
+ (kill-emacs (if (package-installed-p 'telega) 0 1)))" \
+ >/dev/null 2>&1; then
+ echo " ✓ telega Emacs package already installed"
+ return 0
+ fi
+ echo " → installing telega via package.el..."
+ if emacs --batch --eval "(progn
+ (require 'package)
+ (package-initialize)
+ (unless (assoc \"melpa\" package-archives)
+ (add-to-list 'package-archives '(\"melpa\" . \"https://melpa.org/packages/\") t))
+ (package-refresh-contents)
+ (package-install 'telega))" >/dev/null 2>&1; then
+ echo " ✓ telega installed"
+ else
+ echo " ✗ telega install failed"
+ echo " try interactively:"
+ echo " M-x package-refresh-contents"
+ echo " M-x package-install RET telega"
+ return 1
+ fi
+}
+
+main() {
+ echo "→ checking docker..."
+ ensure_docker_installed
+ ensure_docker_running
+ echo "→ preparing telega-server image..."
+ pull_or_announce_image
+ echo "→ checking telega Emacs package..."
+ ensure_telega_package
+ echo "✅ Telega 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/archive/tests/test-setup-telega.bats b/archive/tests/test-setup-telega.bats
new file mode 100644
index 00000000..518ecc7b
--- /dev/null
+++ b/archive/tests/test-setup-telega.bats
@@ -0,0 +1,134 @@
+#!/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: points at make telega-image when no image is set" {
+ TELEGA_DOCKER_IMAGE=""
+ run pull_or_announce_image
+ [ "$status" -eq 0 ]
+ [[ "$output" == *"make telega-image"* ]]
+}
+
+@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"* ]]
+}
+
+# --------------------------- ensure_telega_package ------------------------
+
+@test "ensure_telega_package: fails when emacs is missing" {
+ command() {
+ if [[ "$1" == "-v" && "$2" == "emacs" ]]; then
+ return 1
+ fi
+ builtin command "$@"
+ }
+ run ensure_telega_package
+ [ "$status" -eq 1 ]
+ [[ "$output" == *"emacs not on PATH"* ]]
+}
+
+@test "ensure_telega_package: skips when telega already installed" {
+ # Stub emacs so the first --batch probe (package-installed-p) exits 0.
+ emacs() { return 0; }
+ export -f emacs
+ run ensure_telega_package
+ [ "$status" -eq 0 ]
+ [[ "$output" == *"already installed"* ]]
+}
+
+@test "ensure_telega_package: installs when telega not yet present" {
+ # First call (probe) returns 1 "not installed"; second call (install) returns 0.
+ emacs() {
+ if [[ "$*" == *"package-installed-p"* ]]; then
+ return 1
+ fi
+ return 0
+ }
+ export -f emacs
+ run ensure_telega_package
+ [ "$status" -eq 0 ]
+ [[ "$output" == *"telega installed"* ]]
+}
+
+@test "ensure_telega_package: reports failure when install fails" {
+ # Both calls return non-zero so the install path errors.
+ emacs() { return 1; }
+ export -f emacs
+ run ensure_telega_package
+ [ "$status" -eq 1 ]
+ [[ "$output" == *"install failed"* ]]
+ [[ "$output" == *"M-x package-install"* ]]
+}
diff --git a/archive/tests/test-telega-config--docker-pin.el b/archive/tests/test-telega-config--docker-pin.el
new file mode 100644
index 00000000..8f5b62bd
--- /dev/null
+++ b/archive/tests/test-telega-config--docker-pin.el
@@ -0,0 +1,212 @@
+;;; test-telega-config--docker-pin.el --- Tests for the telega docker image pin -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Tests for pinning the telega-server container image.
+;;
+;; telega infers its image from `telega-tdlib-min-version' and only pins to a
+;; version tag when min and max versions are equal and the version ends in
+;; ".0". This config has min "1.8.66" and max nil, so the inference always
+;; falls through to "zevlg/telega-server:latest" -- a moving tag that can
+;; swap the server out from under a fixed elisp version without notice.
+;;
+;; Since 2026-08-25 the pin names an image built locally from
+;; docker/telega-server/Dockerfile (upstream's image is missing a shared
+;; library, zevlg/telega.el#596). Three files have to agree on that image:
+;; the defcustom default, the Makefile's build tag, and the Dockerfile's
+;; digest-pinned base. The tests below hold them together.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'telega-config)
+
+(defun test-telega-config--file-string (relative)
+ "Return the contents of RELATIVE under `user-emacs-directory'."
+ (with-temp-buffer
+ (insert-file-contents (expand-file-name relative user-emacs-directory))
+ (buffer-string)))
+
+(defun test-telega-config--pin-default ()
+ "Return the defcustom's shipped default, not the live value.
+Customizing the pin (including to nil) is not a test failure; only
+changing the shipped default is."
+ (eval (car (get 'cj/telega-docker-image 'standard-value)) t))
+
+;; -- cj/--telega-docker-pinned-image -----------------------------------------
+
+(ert-deftest test-telega-config-pin-returns-configured-reference ()
+ "Normal: a configured pin is returned verbatim."
+ (let ((cj/telega-docker-image "zevlg/telega-server@sha256:abc123"))
+ (should (equal (cj/--telega-docker-pinned-image)
+ "zevlg/telega-server@sha256:abc123"))))
+
+(ert-deftest test-telega-config-pin-nil-when-unset ()
+ "Boundary: no pin returns nil so telega's own inference stays in charge."
+ (let ((cj/telega-docker-image nil))
+ (should-not (cj/--telega-docker-pinned-image))))
+
+(ert-deftest test-telega-config-pin-nil-for-empty-string ()
+ "Boundary: an empty or whitespace pin is not a reference.
+An empty string would otherwise reach the docker command line as a blank
+image argument, which fails in a way that looks unrelated to this setting."
+ (let ((cj/telega-docker-image ""))
+ (should-not (cj/--telega-docker-pinned-image)))
+ (let ((cj/telega-docker-image " "))
+ (should-not (cj/--telega-docker-pinned-image))))
+
+(ert-deftest test-telega-config-pin-nil-for-non-string ()
+ "Error: a non-string pin is ignored rather than passed to the shell."
+ (let ((cj/telega-docker-image 'latest))
+ (should-not (cj/--telega-docker-pinned-image)))
+ (let ((cj/telega-docker-image 42))
+ (should-not (cj/--telega-docker-pinned-image))))
+
+(ert-deftest test-telega-config-pin-trims-surrounding-whitespace ()
+ "Boundary: a pin with stray whitespace is trimmed, not rejected.
+A trailing newline is easy to introduce when pasting a digest from docker."
+ (let ((cj/telega-docker-image " zevlg/telega-server@sha256:abc123\n"))
+ (should (equal (cj/--telega-docker-pinned-image)
+ "zevlg/telega-server@sha256:abc123"))))
+
+;; -- cj/--telega-docker-image-name (the advice) ------------------------------
+
+(ert-deftest test-telega-config-image-advice-prefers-the-pin ()
+ "Normal: with a pin set, the advice returns it instead of calling telega."
+ (let ((cj/telega-docker-image "zevlg/telega-server@sha256:abc123")
+ (called nil))
+ (should (equal (cj/--telega-docker-image-name
+ (lambda () (setq called t) "zevlg/telega-server:latest"))
+ "zevlg/telega-server@sha256:abc123"))
+ (should-not called)))
+
+(ert-deftest test-telega-config-image-advice-delegates-without-a-pin ()
+ "Boundary: with no pin, telega's own inference is used unchanged.
+Removing the pin must restore stock behavior rather than break the image
+name, so this stays a reversible setting."
+ (let ((cj/telega-docker-image nil))
+ (should (equal (cj/--telega-docker-image-name
+ (lambda () "zevlg/telega-server:latest"))
+ "zevlg/telega-server:latest"))))
+
+(ert-deftest test-telega-config-image-advice-is-named-and-removable ()
+ "Normal: the advice is a named function so it can be removed by reference."
+ (should (fboundp 'cj/--telega-docker-image-name)))
+
+;; -- the shipped default and the files it depends on -------------------------
+
+(ert-deftest test-telega-config-pin-default-matches-makefile-build-tag ()
+ "Normal: the default pin is exactly the tag `make telega-image' builds.
+The image is built locally, so the pin is a tag rather than a registry
+digest. The Makefile owns the tag; the defcustom must name the same one
+or a fresh machine builds an image telega never looks for."
+ (let ((makefile (test-telega-config--file-string "Makefile")))
+ (should (string-match "^TELEGA_IMAGE[ \t]*[?:]?=[ \t]*\\([^ \t\n]+\\)" makefile))
+ (should (equal (test-telega-config--pin-default)
+ (match-string 1 makefile)))))
+
+(ert-deftest test-telega-config-pin-default-is-a-local-tag-not-a-digest ()
+ "Boundary: the default is a plain tag, with no registry digest suffix.
+A locally built image has no RepoDigest, so a digest reference here could
+never resolve."
+ (let ((default (test-telega-config--pin-default)))
+ (should (stringp default))
+ (should (string-match-p "\\`[a-z0-9./-]+:[A-Za-z0-9._-]+\\'" default))
+ (should-not (string-match-p "@sha256:" default))))
+
+(ert-deftest test-telega-config-dockerfile-pins-base-image-by-digest ()
+ "Normal: the Dockerfile's base is an immutable upstream digest.
+This is where the digest guarantee the old pin gave now lives. A tag in
+the FROM line would let upstream swap the base under a rebuild."
+ (let ((dockerfile (test-telega-config--file-string "docker/telega-server/Dockerfile")))
+ (should (string-match-p
+ "^FROM zevlg/telega-server@sha256:[0-9a-f]\\{64\\}[ \t]*$"
+ dockerfile))))
+
+(ert-deftest test-telega-config-dockerfile-adds-the-missing-library ()
+ "Normal: the Dockerfile installs libglycin, the whole reason it exists.
+Upstream's image fails to start without it (zevlg/telega.el#596)."
+ (let ((dockerfile (test-telega-config--file-string "docker/telega-server/Dockerfile")))
+ (should (string-match-p "^RUN apk add .*libglycin" dockerfile))))
+
+;; -- cj/--telega-docker-image-present-p (the docker boundary) ----------------
+;; Exercised against a fake `docker' executable on a private exec-path rather
+;; than by mocking `call-process' (a subr; see the native-comp mocking gotcha).
+
+(defun test-telega-config--with-fake-docker (exit-code thunk)
+ "Call THUNK with a fake `docker' on `exec-path' that exits EXIT-CODE."
+ (let* ((dir (make-temp-file "fake-docker-" t))
+ (script (expand-file-name "docker" dir)))
+ (unwind-protect
+ (progn
+ (with-temp-file script
+ (insert (format "#!/bin/sh\nexit %d\n" exit-code)))
+ (set-file-modes script #o700)
+ (let ((exec-path (list dir)))
+ (funcall thunk)))
+ (delete-directory dir t))))
+
+(ert-deftest test-telega-config-image-present-p-true-when-inspect-succeeds ()
+ "Normal: `docker image inspect' exiting 0 means the image is present."
+ (test-telega-config--with-fake-docker 0
+ (lambda () (should (cj/--telega-docker-image-present-p "cj/telega-server:x")))))
+
+(ert-deftest test-telega-config-image-present-p-nil-when-inspect-fails ()
+ "Boundary: a non-zero exit (no such image) reads as not present."
+ (test-telega-config--with-fake-docker 1
+ (lambda () (should-not (cj/--telega-docker-image-present-p "cj/telega-server:x")))))
+
+(ert-deftest test-telega-config-image-present-p-nil-without-docker ()
+ "Error: with no docker on `exec-path', the helper returns nil instead of
+signalling, so the launcher can still route the user to the make target."
+ (let ((exec-path nil))
+ (should-not (cj/--telega-docker-image-present-p "cj/telega-server:x"))))
+
+;; -- cj/telega refuses to launch against a missing local image ---------------
+
+(ert-deftest test-telega-config-missing-image-message-names-image-and-target ()
+ "Normal: the message names the missing image and the make target that builds it."
+ (let ((msg (cj/--telega-missing-image-message "cj/telega-server:x")))
+ (should (string-match-p "cj/telega-server:x" msg))
+ (should (string-match-p "make telega-image" msg))))
+
+(ert-deftest test-telega-config-launcher-errors-when-pinned-image-is-absent ()
+ "Error: with a pin set and no such image, `cj/telega' stops with the make hint.
+Without this, docker fails to pull a local-only tag and the error names a
+registry the image was never meant to come from."
+ (let ((cj/telega-docker-image "cj/telega-server:x")
+ (launched nil))
+ (cl-letf (((symbol-function 'locate-library) (lambda (&rest _) "telega.el"))
+ ((symbol-function 'cj/--telega-docker-image-present-p) (lambda (_) nil))
+ ((symbol-function 'telega) (lambda (&rest _) (setq launched t))))
+ (let ((err (should-error (cj/telega) :type 'user-error)))
+ (should (string-match-p "make telega-image" (cadr err))))
+ (should-not launched))))
+
+(ert-deftest test-telega-config-launcher-runs-when-pinned-image-is-present ()
+ "Normal: with the pinned image present, `cj/telega' launches telega."
+ (let ((cj/telega-docker-image "cj/telega-server:x")
+ (launched nil))
+ (cl-letf (((symbol-function 'locate-library) (lambda (&rest _) "telega.el"))
+ ((symbol-function 'cj/--telega-docker-image-present-p) (lambda (_) t))
+ ((symbol-function 'telega) (lambda (&rest _) (setq launched t))))
+ (cj/telega)
+ (should launched))))
+
+(ert-deftest test-telega-config-launcher-skips-image-check-without-a-pin ()
+ "Boundary: with no pin, telega infers and pulls its own image; no check runs."
+ (let ((cj/telega-docker-image nil)
+ (checked nil)
+ (launched nil))
+ (cl-letf (((symbol-function 'locate-library) (lambda (&rest _) "telega.el"))
+ ((symbol-function 'cj/--telega-docker-image-present-p)
+ (lambda (_) (setq checked t) nil))
+ ((symbol-function 'telega) (lambda (&rest _) (setq launched t))))
+ (cj/telega)
+ (should-not checked)
+ (should launched))))
+
+(provide 'test-telega-config--docker-pin)
+;;; test-telega-config--docker-pin.el ends here
diff --git a/archive/tests/test-telega-config--server-death.el b/archive/tests/test-telega-config--server-death.el
new file mode 100644
index 00000000..1151fa7e
--- /dev/null
+++ b/archive/tests/test-telega-config--server-death.el
@@ -0,0 +1,131 @@
+;;; test-telega-config--server-death.el --- Tests for the telega-server death alert -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Tests for the telega-server death sentinel. telega's own sentinel only
+;; calls `message' on an abnormal exit, which scrolls away unseen -- so a
+;; dead server reads as a quiet Telegram. These pin the alert that replaces
+;; that silence.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'telega-config)
+
+;; -- cj/--telega-server-death-p ----------------------------------------------
+
+(ert-deftest test-telega-config-death-p-nonzero-status-is-death ()
+ "Normal: a non-zero exit status is an abnormal death."
+ (should (cj/--telega-server-death-p 1))
+ (should (cj/--telega-server-death-p 139)))
+
+(ert-deftest test-telega-config-death-p-segv-signal-is-death ()
+ "Normal: a signal number (SIGSEGV is 11) counts as death.
+This is the observed failure -- the server segfaults rather than exiting."
+ (should (cj/--telega-server-death-p 11)))
+
+(ert-deftest test-telega-config-death-p-zero-is-clean-exit ()
+ "Boundary: exit status 0 is a clean shutdown and must not alert.
+Quitting telega deliberately would otherwise page on every exit."
+ (should-not (cj/--telega-server-death-p 0)))
+
+(ert-deftest test-telega-config-death-p-nil-is-not-death ()
+ "Boundary: nil status (no status available) is not a death."
+ (should-not (cj/--telega-server-death-p nil)))
+
+(ert-deftest test-telega-config-death-p-non-integer-is-not-death ()
+ "Error: a non-integer status returns nil rather than signalling.
+`process-exit-status' is documented to return an integer, but this runs
+inside telega's sentinel where an error would disrupt telega's own cleanup."
+ (should-not (cj/--telega-server-death-p "segfault"))
+ (should-not (cj/--telega-server-death-p 'exited)))
+
+;; -- cj/--telega-server-exit-status ------------------------------------------
+
+(ert-deftest test-telega-config-exit-status-nil-for-non-process ()
+ "Error: a nil or non-process argument yields nil, not a signal.
+The sentinel hands us whatever it has; a bad object must not break telega."
+ (should-not (cj/--telega-server-exit-status nil))
+ (should-not (cj/--telega-server-exit-status "not-a-process")))
+
+;; -- cj/--telega-server-death-body -------------------------------------------
+
+(ert-deftest test-telega-config-death-body-names-status-and-effect ()
+ "Normal: the body carries the status and says coverage is affected.
+The status distinguishes a segfault from a clean kill; the effect is why
+the reader should care."
+ (let ((body (cj/--telega-server-death-body 11 "segmentation fault\n")))
+ (should (string-match-p "11" body))
+ (should (string-match-p "Telegram" body))))
+
+(ert-deftest test-telega-config-death-body-strips-trailing-newline ()
+ "Boundary: a sentinel event string ends in a newline; it must not survive.
+A trailing newline in a desktop notification body renders as dead space."
+ (let ((body (cj/--telega-server-death-body 11 "segmentation fault\n")))
+ (should-not (string-suffix-p "\n" body))))
+
+(ert-deftest test-telega-config-death-body-handles-empty-event ()
+ "Boundary: an empty or nil event still produces a usable body."
+ (should (stringp (cj/--telega-server-death-body 11 nil)))
+ (should (stringp (cj/--telega-server-death-body 11 "")))
+ (should (string-match-p "11" (cj/--telega-server-death-body 11 nil))))
+
+(ert-deftest test-telega-config-death-body-handles-unicode-event ()
+ "Boundary: a non-ASCII event string passes through intact."
+ (let ((body (cj/--telega-server-death-body 1 "ошибка сервера\n")))
+ (should (string-match-p "ошибка" body))))
+
+;; -- cj/--telega-server-notify-death (the advice) ----------------------------
+
+(defmacro test-telega-config--with-status (status captured &rest body)
+ "Run BODY with the exit status forced to STATUS.
+Notification calls are captured into CAPTURED as (TITLE . BODY) pairs."
+ (declare (indent 2))
+ `(let ((,captured nil))
+ (cl-letf (((symbol-function 'cj/--telega-server-exit-status)
+ (lambda (&rest _) ,status))
+ ((symbol-function 'cj/--telega-server-send-notification)
+ (lambda (title body) (push (cons title body) ,captured))))
+ ,@body)))
+
+(ert-deftest test-telega-config-notify-fires-on-abnormal-exit ()
+ "Normal: an abnormal exit sends exactly one notification."
+ (test-telega-config--with-status 11 sent
+ (cj/--telega-server-notify-death nil "segmentation fault\n")
+ (should (= 1 (length sent)))
+ (should (string-match-p "telega" (downcase (car (car sent)))))))
+
+(ert-deftest test-telega-config-notify-silent-on-clean-exit ()
+ "Boundary: a clean exit sends nothing.
+Deliberately quitting telega must not page."
+ (test-telega-config--with-status 0 sent
+ (cj/--telega-server-notify-death nil "finished\n")
+ (should-not sent)))
+
+(ert-deftest test-telega-config-notify-silent-without-status ()
+ "Boundary: no recoverable status sends nothing rather than a bare alert."
+ (test-telega-config--with-status nil sent
+ (cj/--telega-server-notify-death nil "gone\n")
+ (should-not sent)))
+
+(ert-deftest test-telega-config-notify-contains-notifier-errors ()
+ "Error: a failing notifier must not escape into telega's sentinel.
+This runs as :after advice on `telega-server--sentinel'; an error here
+would abort telega's own status handling and its relogin path."
+ (cl-letf (((symbol-function 'cj/--telega-server-exit-status)
+ (lambda (&rest _) 11))
+ ((symbol-function 'cj/--telega-server-send-notification)
+ (lambda (&rest _) (error "notifier unavailable"))))
+ (should (progn (cj/--telega-server-notify-death nil "segfault\n") t))))
+
+(ert-deftest test-telega-config-notify-advice-is-named-and-removable ()
+ "Normal: the sentinel advice is installed by name, so it can be removed.
+An anonymous lambda can't be `advice-remove'd by reference, which strands
+the old advice in a live daemon after the source stops installing it."
+ (should (fboundp 'cj/--telega-server-notify-death))
+ (should (symbolp 'cj/--telega-server-notify-death)))
+
+(provide 'test-telega-config--server-death)
+;;; test-telega-config--server-death.el ends here
diff --git a/archive/tests/test-telega-config.el b/archive/tests/test-telega-config.el
new file mode 100644
index 00000000..54a601c9
--- /dev/null
+++ b/archive/tests/test-telega-config.el
@@ -0,0 +1,58 @@
+;;; test-telega-config.el --- Tests for Telegram (telega) module wiring -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Lightweight asserts that the module loads, exposes the launcher,
+;; sets the docker preference, and registers the C-; G keybinding.
+;; The bulk of telega.el's behaviour is owned upstream; the tests
+;; here only cover what this config wires.
+
+;;; Code:
+
+(require 'ert)
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'telega-config)
+
+(ert-deftest test-telega-config-loads-cleanly ()
+ "Normal: module loads without errors and `provide's its feature."
+ (should (featurep 'telega-config)))
+
+(ert-deftest test-telega-config-launcher-binding-is-telega ()
+ "Normal: =C-; T= invokes the launcher wrapper, which routes to
+`telega' when installed or signals a helpful user-error otherwise.
+
+Was =C-; G= when `T' was contested between org-table and transcription
+menus; both have moved (org-table flattened under `C-; O',
+transcription cleared to M-x), so the natural mnemonic is free."
+ (should (eq (keymap-lookup cj/custom-keymap "T") #'cj/telega)))
+
+(ert-deftest test-telega-config-launcher-without-package-signals-user-error ()
+ "Error: with telega absent, the launcher signals a `user-error' that
+mentions the recovery path instead of falling through to the autoload
+stub's cryptic load-file failure."
+ (cl-letf (((symbol-function 'featurep)
+ (lambda (sym &optional _sub)
+ (and (not (eq sym 'telega)) t)))
+ ((symbol-function 'locate-library)
+ (lambda (lib &rest _) (unless (equal lib "telega") t))))
+ (let* ((err (should-error (cj/telega) :type 'user-error))
+ (msg (error-message-string err)))
+ (should (string-match-p "telega not installed" msg))
+ (should (string-match-p "setup-telega\\.sh\\|package-install" msg)))))
+
+(ert-deftest test-telega-config-launcher-with-package-calls-telega ()
+ "Normal: with telega loadable, the launcher delegates to `telega'."
+ (let (called)
+ (cl-letf (((symbol-function 'featurep)
+ (lambda (sym &optional _sub) (eq sym 'telega)))
+ ;; The pinned image is a local build; treat it as present so
+ ;; this test stays about delegation, not the image check.
+ ((symbol-function 'cj/--telega-docker-image-present-p)
+ (lambda (_) t))
+ ((symbol-function 'telega)
+ (lambda (&rest _) (setq called t))))
+ (cj/telega))
+ (should called)))
+
+(provide 'test-telega-config)
+;;; test-telega-config.el ends here