Add the Sandbar mobile companion PWA

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

README.md

@@ -0,0 +1,76 @@
+# Sandbar mobile
+
+An installable companion for [Sandbar](https://git.veillax.com/Veillax/sandbar): push notifications, on-call actions
+(acknowledge, snooze, escalate, resolve), topics, monitors and Hammerhead tunnel status.
+
+It is a PWA with plain ES modules and no build step. See [docs/design.md](docs/design.md) for why it is not a native app.
+
+## What you need
+
+- A Sandbar server with the mobile endpoints. They are on the `feature/mobile-push` branch of Sandbar and not released yet.
+- HTTPS for the server (or `localhost` while developing). Browsers only allow service workers and push on secure origins.
+
+## Run it against a local Sandbar
+
+Start Sandbar and let it serve this folder:
+
+```
+cd ../sandbar
+SANDBAR_ADMIN_EMAIL=dev@example.com SANDBAR_ADMIN_PASSWORD=choose-a-password \
+SANDBAR_APP_DIR=../sandbar-mobile/public SANDBAR_PUSH_DEV=1 \
+go run ./cmd/sandbar -listen 127.0.0.1:8090 -url http://127.0.0.1:8090
+```
+
+Open `http://127.0.0.1:8090/app/`, sign in, then Settings, Turn on notifications.
+`SANDBAR_PUSH_DEV=1` is only for development: it allows `http` push endpoints and private addresses.
+
+To work on the app files with their own server, run `npm run serve` (port 5173) and start Sandbar with
+`SANDBAR_APP_ORIGIN=http://localhost:5173`. Enter the Sandbar address on the sign-in screen.
+
+## Install it for real
+
+1. Put Sandbar behind HTTPS and set `SANDBAR_URL` and `SANDBAR_APP_DIR` (or host `public/` anywhere and set `SANDBAR_APP_ORIGIN`).
+   Set `SANDBAR_VAPID_SUBJECT=mailto:you@example.com` so push services can reach you. The VAPID key is created on first use
+   and stored in the database; moving to a new database means people must turn notifications on again.
+2. On Android, open `/app/` in Chrome, sign in, turn on notifications, then Install app.
+3. On iPhone (iOS 16.4 or later), open `/app/` in Safari, Share, Add to Home Screen, open it from the Home Screen, then turn on notifications.
+
+To see Hammerhead in the Status tab, set `SANDBAR_HAMMERHEAD_URL`, `SANDBAR_HAMMERHEAD_EMAIL` and
+`SANDBAR_HAMMERHEAD_PASSWORD` on Sandbar, using an account without two-factor sign-in.
+
+## What is in it
+
+| Tab | What it does |
+| --- | --- |
+| Alerts | Open and recent alerts. Acknowledge, Snooze 30 min, Escalate now, Resolve. Updates live and by push. |
+| Topics | Follow topics (they become push subscriptions), read the last 7 days, send a message. |
+| Monitors | Every monitor with up, down or pending, last check and 30 day uptime. Read-only. |
+| Status | Who is on call, and Hammerhead edges (online or offline) when linked. |
+| Settings | Turn push on or off, send a test, list and remove devices, sign out (deletes this phone's API key). |
+
+Notifications for a firing alert carry Acknowledge and Snooze buttons that work without opening the app (Android and desktop).
+
+## Layout
+
+```
+public/            the app, served as is
+  index.html app.css app.js     the page
+  api.js                        Sandbar API client (also used by tests)
+  store.js                      sign-in and topics in IndexedDB, shared with the worker
+  sw.js                         push, notification buttons, offline shell
+scripts/           make-icons.mjs (regenerates the PNG icons), serve.mjs (dev server)
+test/              node --test: API client and service worker
+docs/design.md     why a PWA
+```
+
+```
+npm test
+```
+
+## Not done
+
+- Push delivery was verified with Sandbar's Go tests (the payload is decrypted and the VAPID signature checked), but not
+  through a real Google, Apple or Mozilla push service. The in-app browser used for development refuses service workers,
+  so the service worker is tested in a simulated scope, not in a browser.
+- No offline data beyond the app shell, no incident screens, no editing of monitors or schedules.
+- Hammerhead sign-in with two-factor accounts is not supported.