Escribe tu primer plugin de Herdr en Bash

Un plugin de Herdr es un directorio con un fichero herdr-plugin.toml y algo que se pueda ejecutar. No hay SDK ni lenguaje impuesto: el plugin llama a Herdr por su CLI, y la CLI entera es la API. Vamos a hacer uno que, con un atajo, lea todos los agentes y muestre una notificación con los que están bloqueados.

El manifiesto

Crea el directorio y el manifiesto:

bloqueados/
  herdr-plugin.toml
  bloqueados.sh

id = "programacion-net.bloqueados"
name = "Agentes bloqueados"
version = "0.1.0"
min_herdr_version = "0.9.0"
description = "Avisa de qué agentes esperan una respuesta"
platforms = ["linux", "macos"]

[[actions]]
id = "avisar"
title = "Avisar de agentes bloqueados"
contexts = ["workspace"]
command = ["sh", "bloqueados.sh"]

Cuatro campos son obligatorios: id, name, version y min_herdr_version. Este último es la versión más antigua de Herdr con la que el plugin funciona; Herdr se niega a instalar uno que pida una versión más nueva que la instalada. platforms declara dónde puede correr (en Windows habría que sustituir sh por algo que exista). Y command es una lista argv, no una línea de shell: Herdr no la pasa por ningún intérprete.

El script

#!/bin/sh
# Herdr inyecta HERDR_BIN_PATH con la ruta del binario en marcha.
# Usarlo, y no "herdr" a secas, hace el plugin portable entre sockets Unix y Windows.
herdr="${HERDR_BIN_PATH:-herdr}"

bloqueados=$("$herdr" agent list \
  | jq -r '.result.agents[] | select(.agent_status == "blocked") | "\(.workspace_id) \(.agent)"')

if [ -z "$bloqueados" ]; then
  "$herdr" notification show "Ningún agente bloqueado" --sound none
else
  n=$(printf '%s\n' "$bloqueados" | wc -l | tr -d ' ')
  "$herdr" notification show "$n agente(s) esperando" \
    --body "$(printf '%s' "$bloqueados" | tr '\n' ',')" \
    --sound request
fi

Dos cosas que conviene ver. La primera: agent list devuelve JSON, como casi toda la CLI, y por eso jq es un buen compañero. La segunda: notification show usa la entrega de notificaciones que tengas configurada ([ui.toast]), así que el aviso saldrá donde tú lo tengas decidido.

Enlazar y probar

Mientras desarrollas, no instales: enlaza el directorio.

herdr plugin link ./bloqueados
herdr plugin action list --plugin programacion-net.bloqueados
herdr plugin action invoke programacion-net.bloqueados.avisar

plugin link registra el plugin sin copiarlo; los cambios en el script se aplican en la siguiente invocación. El id de la acción va cualificado con el del plugin (plugin.id.accion), que es lo que evita choques cuando dos plugins llaman igual a una acción. Si algo falla, los registros:

herdr plugin log list --plugin programacion-net.bloqueados

Un atajo

En ~/.config/herdr/config.toml:

[[keys.command]]
key = "prefix+alt+b"
type = "plugin_action"
command = "programacion-net.bloqueados.avisar"
description = "agentes bloqueados"

Recarga con herdr server reload-config y ya está: ctrl+b, alt+b, notificación.

Lo que Herdr pone y lo que no

Cuando ejecuta la acción, Herdr inyecta el contexto en variables de entorno: HERDR_BIN_PATH, HERDR_SOCKET_PATH, el espacio de trabajo, la pestaña y el panel activos, y un HERDR_PLUGIN_CONTEXT_JSON con todo junto, incluido el texto seleccionado o la URL pulsada si la acción viene de un clic. Te da también dos directorios: HERDR_PLUGIN_CONFIG_DIR, para la configuración que el usuario pueda editar (un .env, por ejemplo), y HERDR_PLUGIN_STATE_DIR, para tu estado. El directorio del propio plugin no sirve para eso, porque en las instalaciones desde GitHub es una copia gestionada que se reemplaza al reinstalar.

Lo que no hay en la v1: registro de acciones en tiempo de ejecución (todo va en el manifiesto), almacenamiento gestionado (tus ficheros son tuyos) ni interfaces nativas fuera de la terminal. Sí hay paneles: un plugin puede abrir una terminal propia, como superposición, ventana emergente, división o pestaña, con [[panes]].

Publicarlo

Súbelo a un repositorio público de GitHub, añádele el topic herdr-plugin, y en menos de media hora aparece en el catálogo oficial y en el nuestro. Los demás lo instalan con herdr plugin install tu-usuario/bloqueados. Antes de eso, léete Confianza y seguridad: un plugin corre con el usuario de quien lo instala y puede llamar a toda la CLI, así que lo mínimo es que el manifiesto y el script sean legibles y no sorprendan.

La referencia completa, con eventos, manejadores de enlaces y ganchos de arranque, está en Plugins.