Mashware Alert

Centro de notificaciones inteligente para equipos de desarrollo. Recibe eventos de GitLab (webhooks o polling), evalúa reglas personalizables y envía efectos visuales y sonoros al cliente de escritorio.

Arquitectura

GitLab ──webhook──► Servidor (FastAPI, :8000) ──► Motor de reglas (rule.me)
GitLab ◄──polling──► Servidor                          │
                        │                              ▼
                        └── WebSocket ──► Cliente Tauri (escritorio)

Admin panel (React, :3001) ──► Admin API (FastAPI, :8001)

Requisitos

• Docker + Docker Compose
• Rust + Cargo (para compilar el cliente Tauri)
• Node.js 20

Configuración inicial

1. Variables de entorno

cp .env.dist .env

Edita .env y rellena:

RULES_ENGINE_EMAIL=tu@email.com
RULES_ENGINE_PASSWORD=tu_password
RULES_ENGINE_EMBED_API_KEY=re_live_...
JWT_SECRET=un-secreto-seguro-aqui

2. Entrada en /etc/hosts

echo "127.0.0.1 alert.me" | sudo tee -a /etc/hosts

3. Certificado de rule.me

Visita https://rule.me:8444/rule-engine-widget.iife.js en el navegador y acepta la excepción de seguridad (solo una vez).

Levantar el stack

make up

Servicio	URL
Admin panel	http://alert.me:3001
Admin API	http://alert.me:8001
Servidor webhooks	http://alert.me:8000
Base de datos	localhost:3306

Cliente de escritorio (Tauri)

Compilar

cd client && npx tauri build

Ejecutar

make client-debug   # Con logs
make client         # Modo desarrollo

Configuración

Al primer arranque, la app pide email y password. La configuración se guarda en ~/.config/mashware-alert/config.yaml y el token en el keyring del SO (con fallback al config).

Sonidos personalizados

Coloca archivos .wav en ~/.config/mashware-alert/sounds/. El nombre del archivo (sin extensión) es el que se usa en las reglas. Si no existe un sonido personalizado, se usa el embebido en la app (si existe).

Sonidos incluidos: success, error, alert, info.

Comandos

make up                   # Levantar todos los servicios
make down                 # Parar y eliminar contenedores
make logs                 # Ver logs en tiempo real
make ps                   # Estado de los contenedores
make build                # Reconstruir imágenes
make client               # Cliente Tauri en modo dev
make client-debug         # Cliente compilado con logs

Webhook GitLab

En el admin panel ve a Integrations → GitLab → Configure para obtener la URL y el secret token. Configúralo en GitLab → Settings → Webhooks.

Eventos recomendados: Push, Job, Pipeline, Merge request, Comments.

Polling con token personal

Si no hay webhook configurado, cada usuario puede activar polling desde su panel:

1. Login en el admin panel como usuario
2. Integrations → GitLab → LINK
3. Poner el GitLab username + Personal Access Token (scope read_api)
4. Activar "Enable polling"

El servidor consultará la API de GitLab cada 30 segundos.

---

Efectos

Los efectos son las acciones que ejecuta el cliente de escritorio cuando una regla del motor de reglas matchea. Se envían como JSON por WebSocket:

{ "type": "effect", "effect": { "keyword": "...", "params": { ... } } }

OVERLAY

Muestra un borde de color degradado en los bordes de la pantalla. Transparente y click-through — no interfiere con el trabajo.

{
  "keyword": "OVERLAY",
  "params": {
    "color": "#FF5500",
    "animation": "pulse",
    "duration": 3.0,
    "persistent": true
  }
}

Param	Tipo	Default	Descripción
color	string (hex o nombre)	"#FF5500"	Color del borde. Hex (#EF4444) o nombre (red, yellow, green, blue)
animation	string	"pulse"	Tipo de animación
duration	number	3.0	Duración en segundos (solo para flash)
persistent	boolean	true	Si es true, el overlay no desaparece solo. Si es false, desaparece tras duration

Animaciones disponibles:

Nombre	Comportamiento
pulse	Opacidad sinusoidal suave (0.30 ↔ 0.55). Ideal para estados en curso (deploy, pipeline running)
blink	Parpadeo rápido 0.8s + transición a pulso. Ideal para errores urgentes
flash	Fade out progresivo. Ideal para éxito o eventos informativos que no requieren atención continua
solid	Opacidad fija al 40%. Ideal para estados permanentes

Ejemplos de uso:

// Deploy en curso — pulso amarillo persistente
{ "keyword": "OVERLAY", "params": { "color": "#F59E0B", "animation": "pulse" } }

// Pipeline falló — parpadeo rojo
{ "keyword": "OVERLAY", "params": { "color": "#EF4444", "animation": "blink" } }

// Deploy exitoso — flash verde de 3 segundos
{ "keyword": "OVERLAY", "params": { "color": "#22C55E", "animation": "flash", "duration": 3.0, "persistent": false } }

Cerrar overlay:

• Desde la app: botón DISMISS en el header del dashboard
• Desde el motor de reglas: enviar efecto HIDE

SOUND

Reproduce un archivo de sonido. Soporta reproducción única o en bucle.

{
  "keyword": "SOUND",
  "params": {
    "name": "alert",
    "loop": false
  }
}

Param	Tipo	Default	Descripción
name	string	(requerido)	Nombre del sonido o ruta absoluta al archivo
loop	boolean	false	Si es true, el sonido se repite indefinidamente hasta que se pare

Resolución del nombre:

1. ~/.config/mashware-alert/sounds/<name>.wav — sonido personalizado del usuario
2. Sonido embebido en la app (success, error, alert, info)
3. Ruta absoluta al archivo (ej: /home/user/sounds/custom.wav)

Parar sonido en bucle:

• Desde la app: botón MUTE en el header del dashboard
• Desde el motor de reglas: enviar efecto STOP_SOUND

Ejemplos:

// Sonido de error (una vez)
{ "keyword": "SOUND", "params": { "name": "error" } }

// Sonido de alerta en bucle mientras dura el deploy
{ "keyword": "SOUND", "params": { "name": "alert", "loop": true } }

// Sonido personalizado del usuario
{ "keyword": "SOUND", "params": { "name": "mi-sonido-custom" } }

NOTIFICATION

Muestra una notificación nativa del sistema operativo.

{
  "keyword": "NOTIFICATION",
  "params": {
    "title": "Pipeline Failed",
    "message": "Pipeline #1234 en proyecto api-backend ha fallado"
  }
}

Param	Tipo	Default	Descripción
title	string	"Mashware Alert"	Título de la notificación
message	string	"New event"	Cuerpo de la notificación

HIDE / CLEAR

Oculta el overlay activo.

{ "keyword": "HIDE" }

STOP_SOUND / SILENCE

Para cualquier sonido en reproducción (incluidos los que están en bucle).

{ "keyword": "STOP_SOUND" }

---

Combinaciones típicas de efectos

Una regla puede enviar múltiples efectos. Ejemplos de combinaciones:

Deploy en curso:

[
  { "keyword": "OVERLAY", "params": { "color": "#F59E0B", "animation": "pulse" } },
  { "keyword": "SOUND", "params": { "name": "alert", "loop": true } }
]

Deploy exitoso:

[
  { "keyword": "OVERLAY", "params": { "color": "#22C55E", "animation": "flash", "duration": 3.0, "persistent": false } },
  { "keyword": "SOUND", "params": { "name": "success" } },
  { "keyword": "STOP_SOUND" }
]

Deploy fallido:

[
  { "keyword": "OVERLAY", "params": { "color": "#EF4444", "animation": "blink" } },
  { "keyword": "SOUND", "params": { "name": "error" } }
]

MR aprobado:

[
  { "keyword": "NOTIFICATION", "params": { "title": "MR Approved", "message": "Tu MR ha sido aprobada" } },
  { "keyword": "SOUND", "params": { "name": "info" } }
]

Mención en comentario:

[
  { "keyword": "NOTIFICATION", "params": { "title": "Te han mencionado", "message": "En el proyecto X" } },
  { "keyword": "SOUND", "params": { "name": "alert" } }
]