feat: netcup-standby-guard — flipt netcup-multiplexer naar STANDBY bij comeback (Mac LaunchDaemon)

deploy/README.md

@@ -0,0 +1,47 @@
+# netcup-standby-guard (Mac LaunchDaemon)
+
+Zet de wuzapi-multiplexer op **netcup** automatisch op `STANDBY` zodra netcup weer
+bereikbaar is, maar **alleen** als nextcloud actief is. Voorkomt dubbel-antwoorden in de
+WhatsApp-groepen wanneer netcup terugkomt terwijl nextcloud (na handmatige flip) de
+actieve node is.
+
+## Waarom / invariant
+
+- De multiplexer is de standby-guard (`src/multiplexer.js`): node zonder `STANDBY`
+  routeert webhooks door, node met `STANDBY=1` ACKt alleen (200).
+- Bij een netcup-uitval kan de netcup-unit niet op STANDBY gezet worden → na de
+  handmatige flip van nextcloud naar ACTIEF zijn beide nodes bij netcup-comeback actief.
+  Deze guard flipt netcup dan binnen één poll-interval (60 s) naar STANDBY.
+- **Invariant:** netcup wordt alleen naar STANDBY geflipt als nextcloud bevestigd ACTIEF
+  is (geen `STANDBY=1` in de nextcloud-unit). Staat nextcloud op STANDBY, dan is
+  netcup-actief een bewuste failover (nextcloud-onderhoud) → geen flip.
+
+## Installatie (Mac)
+
+```bash
+sudo -A cp deploy/netcup-standby-guard.sh /usr/local/bin/netcup-standby-guard.sh
+sudo -A chmod 755 /usr/local/bin/netcup-standby-guard.sh
+sudo -A cp deploy/nl.eddydevink.netcup-standby-guard.plist /Library/LaunchDaemons/
+sudo -A launchctl bootstrap system /Library/LaunchDaemons/nl.eddydevink.netcup-standby-guard.plist
+sudo -A launchctl kickstart -k system/nl.eddydevink.netcup-standby-guard   # eerste run direct
+```
+
+- Draait als `eddy` (UserName in plist) → gebruikt de aliassen uit `~/.ssh/config`
+  (`netcup` met key `~/.ssh/netcup_agent_ed25519` zonder passphrase, en `nextcloud`).
+- Notificatie via Gotify: token in `~/.netcup-guard.env` (`GOTIFY_TOKEN=...`, mode 600,
+  gitignored). Ontbreekt het bestand → alleen loggen.
+- Log: `~/Library/Logs/netcup-standby-guard.log`; status: `~/.netcup-guard-state`.
+
+## Handmatige test
+
+```bash
+/usr/local/bin/netcup-standby-guard.sh          # run als eddy
+tail -5 ~/Library/Logs/netcup-standby-guard.log
+```
+
+## Opruimen
+
+```bash
+sudo -A launchctl bootout system/nl.eddydevink.netcup-standby-guard
+sudo -A rm /Library/LaunchDaemons/nl.eddydevink.netcup-standby-guard.plist /usr/local/bin/netcup-standby-guard.sh
+```