feat(infra): auto-commit con 56 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-21 14:22:55 +02:00
parent c1071a82b3
commit 32c7336bf6
56 changed files with 5307 additions and 100 deletions
@@ -0,0 +1,40 @@
+package infra
+
+import (
+	"fmt"
+	"os/exec"
+)
+
+// NotifyDesktop sends a desktop notification on Linux via the `notify-send`
+// binary (libnotify). It is impure: it shells out to an external program.
+//
+// Degradation is intentional and silent: if `notify-send` is not on the PATH,
+// the function returns nil without error. A machine without a notification
+// server is not a failure condition for the caller — the notification is simply
+// skipped. Only a real execution failure of an existing `notify-send` is
+// returned (wrapped with context).
+//
+// When `notify-send` is present it runs:
+//
+//	notify-send --app-name=fleetview --urgency=normal -- <title> <body>
+//
+// The `--` separator guarantees that a title or body starting with "-" is
+// treated as positional text, not as a flag. An empty title falls back to a
+// sensible default; an empty body is accepted by notify-send as-is.
+func NotifyDesktop(title, body string) error {
+	bin, err := exec.LookPath("notify-send")
+	if err != nil {
+		// No notification server / binary on this machine: skip silently.
+		return nil
+	}
+
+	if title == "" {
+		title = "Notificación"
+	}
+
+	cmd := exec.Command(bin, "--app-name=fleetview", "--urgency=normal", "--", title, body)
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("notify-send failed: %w", err)
+	}
+	return nil
+}
@@ -0,0 +1,50 @@
+---
+name: notify_desktop
+kind: function
+lang: go
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "func NotifyDesktop(title, body string) error"
+description: "Lanza una notificacion de escritorio en Linux via el binario notify-send (libnotify). Degradacion limpia: si notify-send no esta en el PATH devuelve nil sin error (no es fallo que la maquina no tenga servidor de notificaciones). Cuando existe ejecuta: notify-send --app-name=fleetview --urgency=normal -- <title> <body>, usando -- para que un texto que empiece por - no se interprete como flag. title vacio cae a un default; body puede ir vacio."
+tags: [orchestration, notify, infra, desktop, libnotify]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: ["fmt", "os/exec"]
+params:
+  - name: title
+    desc: "titulo de la notificacion; si es cadena vacia usa el default 'Notificación'"
+  - name: body
+    desc: "cuerpo de la notificacion; puede ir vacio (notify-send lo acepta)"
+output: "error: nil si la notificacion se mostro o si notify-send no esta instalado (degradacion silenciosa); error envuelto con contexto solo si la ejecucion real de notify-send falla"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "functions/infra/notify_desktop.go"
+---
+
+## Ejemplo
+
+```go
+// Avisar al usuario en el escritorio de que un agente termino.
+err := infra.NotifyDesktop("✅ Agente terminó", "EDA dataset X — revísalo")
+if err != nil {
+    // notify-send existe pero fallo al ejecutarse
+    log.Printf("no se pudo notificar: %v", err)
+}
+// En una maquina sin notify-send, err es nil y la notificacion se omite.
+```
+
+## Cuando usarla
+
+Usala para avisar al usuario en el escritorio cuando un proceso largo o un agente termina su trabajo (fin de un EDA, build, deploy, o tarea desatendida del orquestador). Es el toque final tras una operacion que el humano no esta mirando en directo: dispara la notificacion y sigue, sin preocuparte de si la maquina destino tiene servidor de notificaciones.
+
+## Gotchas
+
+- **Solo Linux con servidor de notificaciones (libnotify).** Depende del binario `notify-send`; en otros SO no aplica.
+- **Headless / sin DBUS no muestra nada pero NO falla.** Si `notify-send` no esta en el PATH, devuelve `nil` (degradacion silenciosa): el caller no se rompe por carecer de notificaciones.
+- **Requiere sesion grafica activa.** Aunque `notify-send` exista, sin una sesion grafica con DBUS la notificacion puede no aparecer; en ese caso `Run()` puede devolver error real, que se devuelve envuelto.
+- **`--` antes de los argumentos posicionales** evita que un `title`/`body` que empiece por `-` se interprete como flag. No lo quites.