docs: record the Devdesk hookshot webhook

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jared Vititoe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -111,7 +111,7 @@ matrix/
 - Build log: `/var/log/cinny-build.log`
 - Nginx site config: `/etc/nginx/sites-available/cinny` (copy in this repo: `cinny/nginx.conf`, synced with live on 2026-09-23)
 - Nginx security headers: `/etc/nginx/snippets/cinny-security-headers.conf` (`cinny/nginx-security-headers.conf`). Included at server level **and** in every `location` that sets its own `add_header`; nginx drops inherited `add_header`s in such blocks, which left static assets without `nosniff` and `/sw.js` without its CSP (cinny #210). Edit the CSP here, not in the site config. **Exception:** `/public/element-call/` (the bundled Element Call, which the app itself frames) uses `cinny-security-headers-framed.conf` (`cinny/nginx-security-headers-framed.conf`), the same headers **without** the CSP. The app CSP's `frame-ancestors 'none'` would block every web call.
-- ⚠️ The `matrix-deploy` hook on 106 has been unreachable since May (webhook bound to `127.0.0.1:9000`), so edits to these files in the repo are **not** auto-deployed there. Apply them by hand (`nginx -t` then `nginx -s reload`) and keep the repo copy in sync.
+- The `matrix-deploy` hook on 106 is served by `webhook-lotus` on `10.10.10.6:9001` (Gitea hook → `http://10.10.10.6:9001/hooks/matrix-deploy`). It was pointed at `:9000` until 2026-09-28, which is bound to `127.0.0.1`, so nothing deployed from May to then (matrix #13). `cinny/config.json` is **merged** into the live file (server-injected values such as `gifApiKey` are kept), and the script installs its own updates (`deploy/lxc106-cinny.sh` → `/usr/local/bin/matrix-deploy.sh`).
 
 ---
 
@@ -132,7 +132,7 @@ Pushes to `main` on `LotusGuild/matrix` automatically deploy to the relevant LXC
 | LXC | Service | IP | Port | Deploys When Changed |
 |-----|---------|----|----|----------------------|
 | 151 | matrix/hookshot | 10.10.10.29 | **9500** | `hookshot/*.js`, `systemd/livekit-server.service`, `livekit/voice-limit-guard.py`, `systemd/voice-limit-guard.service`, `matrixbot/*` |
-| 106 | cinny | 10.10.10.6 | 9000 | `cinny/config.json`, `cinny/upstream-check.sh`, `cinny/lotus-build.sh`, `deploy/hooks-lxc106.json`, `systemd/cinny-upstream-check.cron` |
+| 106 | cinny | 10.10.10.6 | 9001 | `cinny/config.json` (merged), `cinny/nginx.conf`, `cinny/upstream-check.sh`, `cinny/lotus-build.sh`, `cinny/lotus_deploy.sh`, `deploy/hooks-lxc106.json`, `deploy/lxc106-cinny.sh` (self), `systemd/cinny-upstream-check.cron` |
 | 139 | landing/NPM | 10.10.10.27 | 9000 | `landing/index.html` |
 | 110 | draupnir | 10.10.10.24 | 9000 | `draupnir/production.yaml` |
 
@@ -352,6 +352,8 @@ Webhook URL format: `https://matrix.lotusguild.org/webhook/<uuid>`
 | Owncast (Livestream) | `9993e911-c68b-4271-a178-c2d65ca88499` | STREAM_STARTED / STREAM_STOPPED |
 | Bazarr | `470fb267-3436-4dd3-a70c-e6e8db1721be` | Subtitle events (Apprise JSON notifier) |
 | Tinker-Tickets | `6e306faf-8eea-4ba5-83ef-bf8f421f929e` | Custom transformation code |
+| Ci-Alert | `5e7051e7-fd0c-4930-a711-9c67daf6f0b9` | Gitea Actions `notify-failure` jobs (org secret `MATRIX_WEBHOOK_URL`); transform `hookshot/ci-alert.js` |
+| Devdesk | `4a3ccfc9-e1fe-4124-b014-7842fe51b9dc` | DevDesk "Claude needs you" (CT 126 `devdesk-notify-matrix`, URL in `/etc/devdesk/matrix-webhook`); transform `hookshot/devdesk.js`; avatar set via the appservice token |
 
 **Hookshot notes:**
 - Spam and Stuff is intentionally **unencrypted** — hookshot bridges cannot join E2EE rooms
@@ -361,6 +363,7 @@ Webhook URL format: `https://matrix.lotusguild.org/webhook/<uuid>`
 - NPM proxies `/sfu/get` and `/get_token` → `http://10.10.10.29:8070` (lk-jwt-service). Both paths are in `/data/nginx/proxy_host/49.conf` on LXC 139 — **NPM will overwrite these if proxy host 49 is re-saved via the UI; re-add both location blocks after any NPM save**
 - Proxmox sends Discord embed format: `data.embeds[0].{title,description,fields}` — NOT flat fields
 - Transform functions are stored as Matrix room state (`uk.half-shot.matrix-hookshot.generic.hook`) and deployed via `hookshot/deploy.sh`
+- Hook UUIDs are **not** in that state. Hookshot creates them and keeps a `{uuid: name}` map in the `@hookshot` bot's room account data (same event type). Deploying a new transform creates the hook. To look a UUID up on LXC 151, use the appservice token from `/etc/matrix-synapse/hookshot-registration.yaml`: `GET /_matrix/client/v3/user/@hookshot:matrix.lotusguild.org/rooms/<room>/account_data/uk.half-shot.matrix-hookshot.generic.hook?user_id=@hookshot:matrix.lotusguild.org`
 
 **Deploying hookshot transforms manually:**
 ```bash

cinny/config.json

@@ -16,5 +16,17 @@
     "enabled": false,
     "basename": "/"
   },
-  "gifApiKey": ""
+  "gifApiKey": "",
-}
+  "elementCallUrl": "https://call.chat.lotusguild.org/public/element-call/index.html",
+  "statusPages": {
+    "matrix.lotusguild.org": {
+      "url": "https://isitup.lotusguild.org",
+      "slug": "matrix",
+      "groups": {
+        "homeserver": "Homeserver",
+        "calls": "Voice calls",
+        "login": "Login"
+      }
+    }
+  }
+}

cinny/nginx-security-headers.conf

@@ -12,4 +12,4 @@ add_header X-XSS-Protection "1; mode=block" always;
 add_header Referrer-Policy strict-origin-when-cross-origin always;
 add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
 add_header Permissions-Policy 'accelerometer=(), autoplay=(self "https://call.chat.lotusguild.org"), camera=(self "https://call.chat.lotusguild.org"), display-capture=(self "https://call.chat.lotusguild.org"), encrypted-media=(self), fullscreen=(self), geolocation=(self), gyroscope=(), magnetometer=(), microphone=(self "https://call.chat.lotusguild.org"), midi=(), payment=(), usb=()' always;
-add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' blob:; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https://matrix.lotusguild.org https://matrix.org https://*.matrix.org https://mozilla.org https://mozilla.modular.im https://drive.lotusguild.org https://media.giphy.com https://media0.giphy.com https://media1.giphy.com https://media2.giphy.com https://media3.giphy.com https://media4.giphy.com https://www.openstreetmap.org https://tile.openstreetmap.org; font-src 'self' data:; connect-src 'self' https://matrix.lotusguild.org wss://matrix.lotusguild.org https://matrix.org https://*.matrix.org https://mozilla.org https://mozilla.modular.im https://chat.mozilla.org https://vector.im https://api.giphy.com https://*.giphy.com wss:; media-src 'self' https: blob:; frame-src 'self' https:; worker-src 'self' blob:; object-src 'none'; frame-ancestors 'none'; base-uri 'self'; form-action 'self';" always;
+add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' blob:; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https://matrix.lotusguild.org https://matrix.org https://*.matrix.org https://mozilla.org https://mozilla.modular.im https://drive.lotusguild.org https://media.giphy.com https://media0.giphy.com https://media1.giphy.com https://media2.giphy.com https://media3.giphy.com https://media4.giphy.com https://www.openstreetmap.org https://tile.openstreetmap.org; font-src 'self' data:; connect-src 'self' https://matrix.lotusguild.org wss://matrix.lotusguild.org https://isitup.lotusguild.org https://matrix.org https://*.matrix.org https://mozilla.org https://mozilla.modular.im https://chat.mozilla.org https://vector.im https://api.giphy.com https://*.giphy.com wss:; media-src 'self' https: blob:; frame-src 'self' https:; worker-src 'self' blob:; object-src 'none'; frame-ancestors 'none'; base-uri 'self'; form-action 'self';" always;

deploy/lxc106-cinny.sh

@@ -3,7 +3,8 @@
 # Handles: cinny/config.json, cinny/nginx.conf, cinny/upstream-check.sh,
 #          cinny/lotus-build.sh, cinny/lotus_deploy.sh,
 #          deploy/hooks-lxc106.json, systemd/cinny-upstream-check.cron
-# Triggered by: Gitea webhook on push to main
+# Triggered by: Gitea webhook on push to main → http://10.10.10.6:9001/hooks/matrix-deploy
+# (webhook-lotus; the :9000 listener is bound to 127.0.0.1 and unreachable).
 set -euo pipefail
 
 REPO_DIR="/opt/matrix-config"
@@ -27,9 +28,39 @@ else
 fi
 
 if echo "$CHANGED" | grep -q '^cinny/config.json'; then
-    echo "Deploying cinny config.json..."
+    echo "Deploying cinny config.json (merged: keeps server-only values)..."
-    cp "$REPO_DIR/cinny/config.json" /var/www/html/config.json
+    # The live file carries values injected on the server that are empty in git
-    echo "✓ config.json deployed"
+    # (gifApiKey, set by lotus_deploy.sh from GIPHY_API_KEY). A plain copy would
+    # blank them, so repo keys win except where the repo value is empty and the
+    # live one isn't. Backup outside the web root; on any error the live file
+    # is left untouched.
+    mkdir -p /root/config-backups
+    cp -p /var/www/html/config.json "/root/config-backups/config.json.$(date +%Y%m%d%H%M%S)" 2>/dev/null || true
+    if python3 - "$REPO_DIR/cinny/config.json" /var/www/html/config.json <<'PY'
+import json, os, sys, tempfile
+repo_path, live_path = sys.argv[1], sys.argv[2]
+repo = json.load(open(repo_path))
+live = json.load(open(live_path)) if os.path.exists(live_path) else {}
+merged = dict(repo)
+kept = []
+for key, value in live.items():
+    if key in repo and repo[key] in ("", None) and value not in ("", None):
+        merged[key] = value
+        kept.append(key)
+fd, tmp = tempfile.mkstemp(dir=os.path.dirname(live_path))
+with os.fdopen(fd, "w") as f:
+    json.dump(merged, f, indent=2)
+    f.write("\n")
+json.load(open(tmp))
+os.chmod(tmp, 0o644)
+os.replace(tmp, live_path)
+print("kept server values for: " + (", ".join(kept) or "none"))
+PY
+    then
+        echo "✓ config.json deployed"
+    else
+        echo "✗ config.json merge FAILED — live file left unchanged"
+    fi
 fi
 
 if echo "$CHANGED" | grep -q '^cinny/nginx.conf'; then
@@ -80,7 +111,11 @@ if echo "$CHANGED" | grep -q '^deploy/hooks-lxc106.json'; then
     echo "Deploying hooks-lxc106.json..."
     cp "$REPO_DIR/deploy/hooks-lxc106.json" /etc/webhook/hooks.json
     systemctl restart webhook
-    echo "✓ hooks.json deployed, webhook restarted"
+    # webhook-lotus (:9001) serves the same hooks and is the one running THIS
+    # script (Gitea posts matrix-deploy there), so restarting it now would kill
+    # this deploy mid-run: restart it shortly after we exit instead.
+    systemd-run --on-active=15s --unit="webhook-lotus-reload-$(date +%s)" systemctl restart webhook-lotus
+    echo "✓ hooks.json deployed, webhook restarted (webhook-lotus in 15s)"
 fi
 
 if echo "$CHANGED" | grep -q '^systemd/cinny-upstream-check.cron'; then
@@ -90,4 +125,17 @@ if echo "$CHANGED" | grep -q '^systemd/cinny-upstream-check.cron'; then
     echo "✓ cron deployed"
 fi
 
+# Keep the installed copy of this script in step with the repo (the webhook
+# runs /usr/local/bin/matrix-deploy.sh, not the repo file). Checked with bash -n
+# first; takes effect from the next deploy.
+if echo "$CHANGED" | grep -q '^deploy/lxc106-cinny.sh'; then
+    if bash -n "$REPO_DIR/deploy/lxc106-cinny.sh"; then
+        cp "$REPO_DIR/deploy/lxc106-cinny.sh" /usr/local/bin/matrix-deploy.sh
+        chmod +x /usr/local/bin/matrix-deploy.sh
+        echo "✓ matrix-deploy.sh updated"
+    else
+        echo "✗ bash -n FAILED on lxc106-cinny.sh — keeping the installed copy"
+    fi
+fi
+
 echo "=== $(date) === LXC106 deploy complete ==="

hookshot/devdesk.js

@@ -0,0 +1,19 @@
+// DevDesk "Claude needs you" (devdesk#28)
+// Receives: { session, message, url, host, text } from devdesk-notify-matrix on
+// CT 126 when a Claude session waits for input and no browser tab or SSH client
+// is attached to it.
+var session = String(data.session || 'a session');
+var message = String(data.message || 'Claude is waiting for your input');
+var url = data.url ? String(data.url) : '';
+function esc(t) {
+  return t.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+// m.text, not m.notice: notices are muted by default push rules, and this one
+// exists to reach your phone.
+result = {
+  version: 'v2',
+  plain: '🔔 Claude needs you in ' + session + ': ' + message + (url ? ' — ' + url : ''),
+  html: '🔔 <b>Claude needs you</b> in <code>' + esc(session) + '</code>: ' + esc(message)
+    + (url ? ' — <a href="' + esc(url) + '">open in DevDesk</a>' : ''),
+  msgtype: 'm.text',
+};