ezolabs/ezo-watcher

EZO Watcher ist eine Alarmwand und ein Pager, der direkt im Projekt des Benutzers installiert wird: Konfiguration als Code in .watcher/, ein lokaler Node-Prozess, kein Konto. Deine Aufgabe ist die vollständige, geprüfte Installation – keine Liste von Vorschlägen.

Die CLI ist die Quelle der Wahrheit. Jedes Thema unten wird daraus ausgegeben: watcher skills <topic> (Themen: install, discover, sources, channels, hosting, cloudflare, netdata, operate, fix, telemetry), oder lies references/<topic>.md neben dieser Datei. Führe jeden Befehl als watcher <verb> aus, niemals das nackte Wort (doctor kollidiert mit dem eigenen /doctor des Host-Agenten).

CLI installieren

CI=1 npm_config_yes=true npm i -g ezo-watcher
watcher --version

Keine globale Installation: npx -y ezo-watcher <verb> führt dieselbe CLI aus. Aus einem Checkout: npm ci && npm run build && npm link. Node 24+. Vollständige Details, einschließlich der Installation des neuesten Hauptzweigs von GitHub: watcher skills install.

Der Ablauf

Wenn .watcher/ bereits existiert, führe zuerst watcher doctor --json und watcher scan --json aus und füge dann nur das hinzu, was das Ranking als fehlend bezeichnet; initialisiere nicht über eine funktionierende Installation hinweg neu.

1. Init. watcher init im Projektstamm. Idempotent, fragt nie nach; schreibt .watcher/config.json, .watcher/.env (0600), .watcher/data/, ignoriert die letzten beiden im Git, wählt einen freien Port ab 7717, gibt eine erste Doctor-Zusammenfassung aus.
2. Scan. watcher scan --json → {signals, suggestedCommands}. In einer kleinen, manuell beschrifteten Stichprobe fand der Prototyp 15 von 19 HTTP/TLS-Punkten, aber nur 2 von 10 Stille-Punkten (watcher skills discover): Behandle seine Befehle als Kandidaten, führe dann den untenstehenden Stille-zuerst-Durchlauf durch, indem du den Code liest.
3. Wähle nach dem Ranking (nächster Abschnitt). Eine Quelle pro echtem Punkt; erfinde niemals eine Quelle, um grün auszusehen.
4. Hinzufügen. Für jede ausgewählte Quelle: watcher add <kind> --id <id> … --found-at <file:line> --read "<was es beweist>". Die Optionen --found-at/--read sind Herkunftsnachweise, und watcher doctor warnt ohne sie. --dry-run zeigt eine Vorschau. Dann ein Kanal: watcher add channel <type> --id <id> … (siehe watcher skills channels). Wenn keine Anmeldedaten verfügbar sind – eine box ohne Benutzeroberfläche, kein Anbieterkonto, ein Benutzer, der keinen Pager gewählt hat – füge den anmeldeinformationsfreien Fallback hinzu: watcher add channel file --id local: Es schreibt eine JSON-Zeile pro Benachrichtigung unter .watcher/data/ und ist ein echter, testbarer Kanal, kein Platzhalter. watcher add … --replace überschreibt eine bestehende ID; watcher rm <id> entfernt eine.
5. Doctor-Schleife. watcher doctor --json; wenn ok:false, behebe den ersten fail über dessen next und führe es erneut aus. Wenn channel.missing warnt und der Benutzer möchte, dass ein Telefon klingelt, führe jetzt den Kanal von Schritt 8 aus und komme zurück. Exit 0 ist bestanden, 1 ist fehlgeschlagen, 64 ist Nutzungsfehler.
6. Ausführen. watcher run --detach (oder watcher service install, damit es einen Neustart überlebt). Dann watcher doctor --live --json, um den laufenden Server zu lesen.
7. Beweisen. watcher doctor --live --prove --json ausführen, bis es {"ok": true, "live": true} zurückgibt. --prove verschiebt den eigenen Messwert jeder Quelle über ihren Schwellenwert und schlägt fehl, es sei denn, die Regel schlägt tatsächlich um (source.assertion-not-red; eine nichtssagende http-probe-Behauptung schlägt fehl mit source.assertion-vacuous): Eine http-probe-Antwort wird verändert, ein Heartbeat wird nach einem verpassten Durchlauf plus seiner Gnadenfrist ausgewertet, ein Host-Messwert wird über seine Festplatten-/Speicher-/Lastschwellenwerte verschoben, eine tcp-Verbindung schlägt fehl, ein Ablaufdatum fällt in pageDays. Eine Art, deren Alarm das ist, was ihr Sender meldet (grafana, vmalert, sentry, netdata, feed, webhook), ist ein benannter source.prove-unsupported-Sprung, niemals ein Fehler. Wenn das Projekt keinen Server und keinen geplanten Job hat, füge watcher add host --id host hinzu – die Maschine selbst, lokal gelesen ohne installierte Software – und beweise es. Nur ein Projekt mit keinem Server, keinem geplanten Job und keinem zu überwachenden Host führt watcher doctor --no-runtime-surface --json aus → {"ok": true, "live": false, "reason": "no-runtime-surface"}, klar gemeldet; eine konfigurierte Quelle gewinnt immer über --no-runtime-surface (der Bericht warnt dann doctor.no-runtime-surface-ignored). Rufe eine nicht bewiesene Installation nicht abgeschlossen.
8. Alarmieren. Füge einen Kanal hinzu und führe watcher test-alert aus; bestätige, dass es auf dem relevanten Gerät angekommen ist. Fehlende Anmeldedaten sind ein benannter Sprung, niemals ein Bestehen.
9. Hosting (optional). Die Leiter ist lokal → Dienst → Docker/VPS → Cloudflare Tunnel (Standard für "mit meinem Cloudflare-Key hosten") → Container Beta. watcher skills hosting, watcher skills cloudflare.
10. Installiere den Skill für das nächste Mal. watcher skills install --target all --dir . schreibt es in das Projekt. Führe in Claude Code anschließend /reload-skills aus – ein Skills-Verzeichnis auf oberster Ebene, das mitten in der Sitzung erstellt wurde, wird sonst nicht erkannt.

Am zweiten Tag – die Wand lesen, bestätigen, kommentieren, stummschalten, parken, erneut prüfen – ist watcher skills operate.

Wenn etwas kaputt geht

Ein Vorfall ist eine Behauptung mit Beweisen, keine Benachrichtigung. Der vollständige Ablauf ist watcher skills fix:

1. watcher status --brief für eine Zeile, oder watcher incidents --output json für die Schlüssel (MCP: watch_state, dann list_incidents).
2. get_fix_context { key } (CLI: watcher incident <key> --fix-context): Der Vorfall, die Quell- und Zielkonfiguration mit Anmeldedaten als Umgebungsvariablennamen, die Regelbehauptungen und diejenige, die fehlgeschlagen ist, wo der Endpunkt gefunden wurde, die letzte gute neben der letzten schlechten Beobachtung, der genaue Befehl, der die Prüfung erneut ausführt, und next.
3. Reproduziere es mit diesem Befehl. Ein Schwellenwert ist keine Ursache.
4. Behebe die Ursache, stelle erneut bereit oder starte neu, damit die Behebung wirksam wird.
5. verify_fix { key, by } (CLI: watcher recheck <key> --wait): Es prüft erneut, wartet auf die frische Antwort der Quelle und zeichnet die Bestätigung auf, wenn alle Alarme gelöst sind – oder sagt, welche Behauptung immer noch fehlschlägt, damit die Behebung repariert werden kann. Markiere einen Vorfall niemals als gelöst, bevor eine erneute Prüfung grün ist; park ist für eine behobene Lösung, die zusammengeführt, aber noch nicht live ist, confirm_resolution für eine, die die Quelle bereits geschlossen hat.
6. comment, was du auf dem Weg gefunden hast. Eine stille Behebung hinterlässt der nächsten Person nichts.

Ranking: Was überwacht werden soll, in der Reihenfolge

1. Die tiefste Bereitschaftsroute des Produktionsprozesses, die ein Feld behauptet, das sich ändert, wenn eine Abhängigkeit ausfällt. Niemals ein hartcodiertes {"ok": true} / {"status": "ok"} – das ist Liveness, und es kann für den relevanten Fehler nicht rot werden.
2. Ein Bereitschaftsprobe, die die Plattform bereits deklariert: /readyz, /health/ready, ein compose healthcheck, ein Kubernetes readinessProbe, ein Fly/Railway/Render Health-Pfad. Spiegele es von außen mit demselben Pfad und Port.
3. Kein Server → ein Heartbeat pro geplantem Job. Stille ist das Signal.
4. Kein Server und kein geplanter Job → watcher add host --id host (Last, Speicher, freier Speicherplatz, optional eine PID-Datei; nichts installiert) und beweise es. Nur kein Server, kein geplanter Job und kein zu überwachender Host → watcher doctor --no-runtime-surface --json, melde NO_RUNTIME_SURFACE, stoppe. Eine konfigurierte Quelle gewinnt immer über --no-runtime-surface. Erfinde niemals eine Quelle.
5. Dann die Systeme, die bereits existieren – Sentry, Grafana, Netdata, ein eingehender Sender – anmeldeinformationsgebunden. Fehlende Anmeldedaten sind ein benannter Sprung mit einem Code und einem next, niemals ein stilles Bestehen.

Stille zuerst (die Scan-Ergebnisse übersehen diese)

Lies den Code für diese sechs Klassen; jede wird zu einem watcher add heartbeat oder einem watcher add webhook --stale-after:

1. Zeitpläne, die zur Installationszeit generiert werden – Heredocs in install.sh/setup.*, die eine plist, Unit oder crontab schreiben, launchctl load, systemctl enable, crontab schreibt.
2. Launchd/systemd/cron zur Laufzeit erstellt – .plist-Vorlagen, OnCalendar=, StartInterval, KeepAlive, node-cron, schedule(, setInterval um einen Job, celery beat. Ein Heartbeat pro Job (--every/--schedule + --grace); N Jobs bedeuten N Quellen.
3. Pull-Queue-Worker – worker, queue, bullmq, sqs, claim, lease, dequeue. Fehler ist die Warteschlangentiefe oder kein Fortschritt, kein Port: Sende einen Heartbeat auf dem Erfolgspfad oder schiebe einen checks.list-Eintrag mit state: failing.
4. Veralterung in der eigenen Konfiguration des Produkts – staleAfterSec, presenceTtlSec, maxAge, ttl, refreshInterval, lastRunAt. Erzwinge dasselbe Fenster: watcher add webhook --id <sender> --token-env <ENV> --stale-after-sec <sec>.
5. Beschreibbarkeit des Statusverzeichnisses – mkdir, state/, data/, sqlite, Lock-Dateien. Sende nur nach einem erfolgreichen Schreibvorgang; ein bloßes test -w ist keine Quelle.
6. Abhängigkeitsendpunkte, die als Codekonstanten gehalten werden – process.env.X ?? "https://…", Host:Port-Literale, gRPC/ClickHouse/LLM-Basen. watcher add http-probe (HTTPS GET) oder watcher add tcp-probe --host --port, mit --found-at der Konstanten.

Setze den Ping auf den Erfolgspfad des Jobs – POST /ingest/heartbeat/<id>, mit /fail für einen fehlgeschlagenen Durchlauf und /<exit-code> für einen bestimmten. watcher add heartbeat prägt das Token in .watcher/.env (0600), wenn die benannte Variable noch keinen Wert hat, oder schreibt das übergebene --secret-value und gibt die genauen Zeilen aus ($NIGHTLY_TOKEN unten ist der Name, den es für --id nightly wählt; ein übergebenes --token-env ist die Variable, die es stattdessen ausgibt):

set -a; . .watcher/.env
curl -fsS -m 10 "${WATCHER_URL:-http://127.0.0.1:7717}/ingest/heartbeat/<id>?token=$NIGHTLY_TOKEN"                 # nach einem erfolgreichen Durchlauf
curl -fsS -m 10 "${WATCHER_URL:-http://127.0.0.1:7717}/ingest/heartbeat/<id>/fail?token=$NIGHTLY_TOKEN"            # nach einem fehlgeschlagenen Durchlauf
curl -fsS -m 10 "${WATCHER_URL:-http://127.0.0.1:7717}/ingest/heartbeat/<id>/<exit-code>?token=$NIGHTLY_TOKEN"     # mit dem Exit-Code des Jobs

Ein Collector, der kein einzelner Job ist, pusht stattdessen seine gesamte Liste: POST /ingest/<source> mit {"checks":{"list":[{"id":"…","service":"…","state":"ok","lastRunAt":"…"}]}} – die vollständige Form und Zustände sind in watcher skills sources.

Wenn eine Health-Route nur ein Literal zurückgibt, finde eine tiefere oder füge eine hinzu: GET /readyz → 200 {"db":{"ok":true}}, wenn die Abhängigkeit antwortet, 503 {"db":{"ok":false}}, wenn nicht. Das Bearbeiten des Projekts des Benutzers ist erlaubt – du bist der Agent, der die Datei schreibt. Beantworte dann das sich ändernde Feld, niemals {"ok":true}.

Regeln

• Richte eine Quelle niemals auf das eigene /healthz des Watcher – source.self-probe lehnt es ab.
• Eine Quelle muss etwas behaupten, das umkippen kann. Ein bloßes 200 ist nur Liveness (source.bare-200); watcher doctor --live --prove ist das Tor, --found-at ist eine Warnung (source.untraced).
• Geheimnisse sind Umgebungsvariablennamen in der Konfiguration und Werte nur in .watcher/.env. Lies niemals .env-Werte während des Scannens, committe niemals .watcher/.env oder .watcher/data/.
• Ein funktionierender Kanal ist besser als fünf konfigurierte. Beweise es mit watcher test-alert. Gar keine Anmeldedaten? watcher add channel file --id local und beweise das: Die Datei ist ein echter Kanal, und fehlende Anmeldedaten sind ein benannter Sprung, niemals ein Bestehen.
• Melde, was du bewiesen hast – hinzugefügte Quellen, Befehlsausgabe und jeden benannten Sprung. Wenn der Agent eine Sprosse nicht abschließen kann (fehlende Anmeldedaten, keine Zone), sage in einer Zeile, welche und warum.

Mehr Details, wenn ein Schritt sie benötigt: watcher skills discover (vollständiger Signalkatalog und die Stille-Checkliste), watcher skills sources (jede Art, Flags, Beispiele), watcher skills channels, watcher skills hosting, watcher skills cloudflare, watcher skills netdata, watcher skills operate (MCP-Werkzeuge und Vorfall-Triage).