Plugins

Los plugins de Herdr son paquetes de flujo de trabajo ejecutables y compartibles. Un plugin puede ser un script de Bash, una aplicación en JavaScript, un script de Lua, un binario en Rust o cualquier otro comando argv que tu máquina pueda ejecutar. Herdr es dueño de la superficie de acogida: instalación, validación del manifiesto, atajos, paneles de terminal, eventos, contexto de invocación y acceso al socket. El plugin es dueño de su lenguaje, sus dependencias, sus ficheros y su estado duradero.

Los plugins existen para que Herdr pueda mantenerse ligero. El núcleo se centra en espacios de trabajo de terminal, paneles, agentes y una CLI y API de socket estables. Los plugins convierten esa superficie de extensión en flujos de trabajo reutilizables que la gente puede construir, instalar y compartir sin añadir cada flujo al propio Herdr.

Un plugin es un directorio con un manifiesto herdr-plugin.toml y comandos que Herdr puede lanzar. Herdr valida el manifiesto, inyecta el contexto de ejecución, arranca los comandos declarados y registra sus salidas. Los comandos llaman de vuelta a Herdr a través de la CLI o del socket cuando necesitan hacer algo más.

No hay un SDK de plugins aparte ni un conjunto restringido de comandos. Toda la CLI de Herdr es la API de plugins. Cada comando de la referencia de la CLI está disponible para un plugin, y un plugin puede ejecutar cualquier cosa que tú puedas ejecutar como herdr .... La mayoría de los plugins deberían llamar a Herdr a través de HERDR_BIN_PATH, que apunta al binario de Herdr en ejecución. Así los plugins son portables entre sockets Unix y tuberías con nombre de Windows. Usa la API de socket cuando quieras enviar tú mismo las peticiones JSON en bruto.

El registro de acciones en tiempo de ejecución y las interfaces nativas de plugin fuera de la terminal no forman parte de la v1 de plugins. Las acciones, los ganchos de eventos, los paneles y los manejadores de enlaces se declaran todos en el manifiesto.

Confianza y seguridad

Un plugin es código normal que se ejecuta en tu máquina. Sus comandos de construcción y de ejecución corren con tu usuario, heredan tu entorno y pueden llamar a toda la CLI de Herdr. Trata un plugin como cualquier extensión que añadas a un editor, a un shell o a un agente de programación.

Instala o enlaza plugins solo de autores y repositorios de confianza. Antes de instalar o enlazar uno, échale un vistazo al manifiesto herdr-plugin.toml y a los scripts o binarios que ejecuta. En terminales interactivas, herdr plugin install muestra una vista previa de la fuente y de los comandos que va a ejecutar, para que puedas revisarlos antes de confirmar. Usa --yes con las fuentes en las que ya confíes, y fija --ref cuando quieras una revisión concreta.

Herdr valida el manifiesto y guarda la configuración y el estado de cada plugin en su propio directorio, pero no revisa el código del plugin ni lo aísla. Los plugins de terceros vienen de sus autores, no de Herdr; decidir si ejecutarlos es responsabilidad tuya.

Manifiesto

El manifiesto es el contrato entre Herdr y el plugin. Declara los metadatos del paquete, las plataformas compatibles, los comandos de construcción opcionales y los puntos de entrada que Herdr puede ejecutar.

id = "example.layout"
name = "Layout"
version = "0.1.0"
min_herdr_version = "0.7.0"
description = "Apply project layouts"
platforms = ["linux", "macos", "windows"]

[[build]]
command = ["npm", "ci"]

[[build]]
command = ["npm", "run", "build"]
platforms = ["linux", "macos"]

[[startup]]
command = ["node", "dist/restore.js"]

[[actions]]
id = "apply"
title = "Apply layout"
contexts = ["workspace"]
command = ["node", "dist/apply.js"]

[[events]]
on = "worktree.created"
command = ["herdr", "workspace", "list"]

[[panes]]
id = "board"
title = "Project board"
placement = "overlay"
command = ["herdr-board"]

[[link_handlers]]
id = "github-issue"
title = "Open GitHub issue"
pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$"
action = "apply"

Los campos de nivel superior id, name, version y min_herdr_version son obligatorios. Pon en min_herdr_version la versión más antigua de Herdr que admita las API de plugin, los nombres de evento y los campos de manifiesto que usa tu plugin. Herdr se niega a enlazar o instalar un plugin cuando su versión mínima es más nueva que el binario actual. description es opcional. Los ids de plugin pueden usar letras ASCII, dígitos, punto, dos puntos, guion bajo y guion.

Los ids de acción, de panel y de manejador de enlaces son ids locales dentro del plugin. Pueden usar letras ASCII, dígitos, dos puntos, guion bajo y guion, pero no puntos. Cada tipo de id debe ser único dentro del plugin. Herdr cualifica los ids de acción como plugin.id.accion cuando necesita un nombre único global.

Usa platforms = ["linux", "macos", "windows"] para declarar dónde puede ejecutarse el plugin. Los comandos de construcción, los ganchos de arranque, las acciones, los ganchos de eventos, los paneles y los manejadores de enlaces también pueden declarar sus propias platforms; las de cada elemento prevalecen sobre la lista de nivel superior. Los plugins locales sin platforms de nivel superior se enlazan con un aviso.

Los valores de command son listas argv. Herdr no los pasa por un shell, así que no hay expansión de shell a menos que tu comando arranque uno. Pon el comportamiento específico de cada lenguaje en tu script o binario.

Tu primer plugin

Empieza con un directorio que contenga herdr-plugin.toml y un script o programa ejecutable:

my-plugin/
  herdr-plugin.toml
  index.js

id = "example.workspace-tools"
name = "Workspace Tools"
version = "0.1.0"
min_herdr_version = "0.7.0"
description = "Small workspace helpers"
platforms = ["linux", "macos", "windows"]

[[actions]]
id = "list-workspaces"
title = "List workspaces"
contexts = ["workspace"]
command = ["node", "index.js"]

Dentro del comando, llama de vuelta a Herdr con HERDR_BIN_PATH:

const { spawnSync } = require("node:child_process");

const herdr = process.env.HERDR_BIN_PATH ?? "herdr";
const result = spawnSync(herdr, ["workspace", "list"], {
  encoding: "utf8",
  stdio: ["ignore", "pipe", "pipe"],
});

process.stdout.write(result.stdout);
process.stderr.write(result.stderr);
process.exit(result.status ?? 1);

Este ejemplo usa Node, pero nada en los plugins exige Node. El manifiesto podría lanzar Bash, PowerShell, Python, Rust, Go, Lua, Bun o cualquier otro comando disponible en la máquina del usuario.

Instalar y enlazar

Instala un plugin de ejemplo:

herdr plugin install ogulcancelik/herdr-plugin-examples/agent-telegram-notify
herdr plugin config-dir examples.agent-telegram-notify
herdr plugin list
herdr plugin action list --plugin examples.agent-telegram-notify

Cuando estés escribiendo un plugin local, enlaza el directorio de trabajo en su lugar:

herdr plugin link /ruta/al/plugin
herdr plugin config-dir example.layout
herdr plugin action list --plugin example.layout
herdr plugin action invoke example.layout.apply
herdr plugin pane open --plugin example.layout --entrypoint board
herdr plugin log list --plugin example.layout

plugin install solo acepta la forma abreviada de GitHub, como owner/repo/subdir. Clona con git, muestra una vista previa en terminales interactivas, ejecuta los comandos de construcción admitidos, y después guarda la copia bajo los datos de plugins gestionados por Herdr y la registra. Usa --yes para instalaciones no interactivas. Reinstalar un plugin gestionado desde GitHub reemplaza esa copia gestionada. Los plugins instalados y enlazados, incluido su estado de activación, son globales para el usuario actual y están disponibles en todas las sesiones de Herdr. Tanto plugin install como plugin link pueden registrar plugins sin que haya un servidor de Herdr en marcha. Los plugins instalados solo en una sesión con nombre con Herdr 0.7.3 hay que instalarlos o enlazarlos de nuevo. La configuración y el estado existentes se conservan. Instalar sobre un plugin enlazado localmente se rechaza; desenlaza o desinstala antes el plugin local. plugin install y plugin link crean los directorios de configuración y estado del plugin, y plugin config-dir <id> imprime el directorio de configuración, útil para documentación de instalación y scripts de shell.

plugin uninstall <id-o-fuente> desregistra el plugin. En las instalaciones gestionadas desde GitHub también elimina la copia gestionada, y acepta tanto el id del plugin como la misma forma abreviada owner/repo[/subdir...] que usa la instalación. plugin unlink <id> solo desregistra el plugin y no toca los ficheros, lo que resulta útil para el desarrollo local. En la v1 no hay un plugin update aparte; reinstala desde GitHub para refrescar un plugin gestionado.

El repositorio de recetas de ejemplo es ogulcancelik/herdr-plugin-examples. Contiene plugins de ejemplo separados en subdirectorios, como agent-telegram-notify, github-link-preview y dev-layout-bootstrap. Úsalos como ejemplos para copiar; Herdr no los mantiene como plugins oficiales.

Comandos de construcción

Los comandos de construcción se ejecutan durante plugin install desde GitHub, después de confirmar y antes de que Herdr registre el plugin. Si un comando de construcción falla, la instalación se aborta y el plugin no se registra. plugin link no ejecuta comandos de construcción; los autores locales construyen su árbol de trabajo por su cuenta. Los comandos de construcción pueden generar ficheros, pero cambiar herdr-plugin.toml después de la vista previa aborta la instalación. Los fallos de construcción muestran el id del plugin, el índice del comando, el directorio de trabajo, el comando, el código de salida o el error de arranque, y la salida estándar y de error recortadas, sin interpretar lo que dice la herramienta.

Los comandos de construcción también son comandos argv sin más, pero no reciben el contexto de ejecución del plugin ni las variables del socket de Herdr. Los autores deberían documentar las herramientas del sistema necesarias, como cargo, npm, bun o lua; Herdr informa de los fallos de construcción pero no instala las herramientas que falten.

Ganchos de arranque

Los comandos [[startup]] se ejecutan una vez por cada plugin activado, después de que Herdr restaure la sesión y su socket de API esté listo. Vuelven a ejecutarse cuando un servidor nuevo toma el relevo durante un traspaso en caliente, pero no cuando un cliente se conecta, se recarga la configuración o se enlaza o activa un plugin. Herdr los arranca de forma asíncrona y registra su finalización en el registro normal de comandos de plugin. Un fallo en el arranque no detiene el servidor.

Los ganchos de arranque son comandos de inicialización de una sola ejecución, no demonios supervisados. Un gancho debería restaurar el estado propio del plugin, llamar a las API de Herdr que necesite y terminar. Por ejemplo, un plugin puede guardar una vista declarativa de agentes bajo HERDR_PLUGIN_STATE_DIR, y leerla y volver a aplicarla desde su gancho de arranque.

Los ganchos de arranque reciben el entorno de ejecución normal de los plugins y HERDR_PLUGIN_EVENT=startup. La vista previa de instalación lista todos los comandos de arranque, para que el usuario pueda revisar el código que se ejecutará automáticamente.

Comandos y entorno

Los comandos de ejecución se lanzan con el directorio del plugin como directorio de trabajo. Herdr inyecta HERDR_SOCKET_PATH, HERDR_BIN_PATH, HERDR_ENV=1, HERDR_PLUGIN_ID, HERDR_PLUGIN_ROOT, HERDR_PLUGIN_CONFIG_DIR, HERDR_PLUGIN_STATE_DIR, HERDR_PLUGIN_CONTEXT_JSON, y los HERDR_WORKSPACE_ID, HERDR_TAB_ID y HERDR_PANE_ID que estén disponibles. Los comandos de acción reciben además HERDR_PLUGIN_ACTION_ID; los ganchos de arranque y de eventos reciben HERDR_PLUGIN_EVENT (startup en los de arranque), los de eventos reciben además HERDR_PLUGIN_EVENT_JSON, y los comandos de panel reciben HERDR_PLUGIN_ENTRYPOINT_ID.

HERDR_PLUGIN_ROOT es el directorio del plugin instalado o enlazado. No guardes ahí credenciales del usuario ni estado duradero, porque las raíces de los plugins instalados desde GitHub son copias de código gestionadas. Pon la configuración editable por el usuario, como ficheros .env, bajo HERDR_PLUGIN_CONFIG_DIR, y el estado local de ejecución bajo HERDR_PLUGIN_STATE_DIR. Herdr crea esos directorios y rellena HERDR_PLUGIN_CONFIG_DIR a partir de las ubicaciones antiguas de configuración de plugins cuando existen, pero no valida, sincroniza ni borra su contenido. El plugin es dueño del formato de los ficheros y de su ciclo de vida.

HERDR_PLUGIN_CONTEXT_JSON puede incluir campos de espacio de trabajo, pestaña, panel enfocado, worktree, agente, texto seleccionado, URL pulsada y manejador de enlaces cuando estén disponibles para esa invocación. Los plugins de shell pueden leer las variables de entorno individuales para los ids habituales, o analizar el JSON de contexto para la forma completa.

Usa HERDR_BIN_PATH cuando un plugin necesite llamar a Herdr de forma portable desde Node, PowerShell, Bash u otro entorno. El transporte de socket en bruto que hay detrás de HERDR_SOCKET_PATH depende del sistema: los clientes Unix conectan a una ruta de socket Unix, mientras que los de Windows conectan a una tubería con nombre. Las llamadas a la CLI a través de HERDR_BIN_PATH evitan esa diferencia. Mira la referencia de la CLI para los comandos disponibles y la API de socket para la forma de las peticiones en bruto.

Paneles

El placement de un panel en el manifiesto es overlay por defecto, que abre una superposición temporal ampliada sobre el panel activo y restaura el foco y la ampliación anteriores al cerrarse. Una petición plugin.pane.open puede sustituir la colocación del manifiesto por overlay, popup, split, tab o zoomed.

placement = "popup" abre una ventana emergente de terminal, modal de sesión, sin cambiar la disposición en mosaico. Acepta campos opcionales width y height en el manifiesto o en la petición de apertura; omítelos para la ventana por defecto de medio tamaño, usa números para dimensiones en celdas de la terminal exterior, o cadenas como "80%" para un porcentaje del área de la terminal. Recibe toda la entrada de la terminal, incluido Escape, y se cierra cuando el comando termina o se envía una petición popup.close. Las dimensiones menores que el mínimo de la ventana se ajustan.

Declara la colocación directamente en el punto de entrada del panel cuando el panel deba ser siempre transitorio:

[[panes]]
id = "picker"
title = "Picker"
platforms = ["linux", "macos"]
placement = "popup"
width = "80%"
height = 20
command = ["sh", "picker.sh"]

Los paneles de plugin de tipo división, pestaña, ampliado y superposición son paneles normales de Herdr una vez abiertos. Los plugins pueden llamar a las API estándar de panel, como pane.move, pane.swap, pane.resize y pane.zoom, por el socket o la CLI; Herdr mantiene la propiedad del panel de plugin ligada al panel subyacente cuando se mueve entre pestañas o espacios de trabajo. Una ventana emergente es un recurso único de la sesión, no un panel de Herdr: no tiene ID de panel, no cambia el contexto de foco del plugin, no emite eventos de ciclo de vida de panel y no participa en las API de panel, disposición, persistencia ni agentes. Su proceso no recibe HERDR_PANE_ID; el panel en mosaico subyacente sigue disponible a través de HERDR_PLUGIN_CONTEXT_JSON. Abrir una ventana emergente devuelve ui_busy mientras estén activos Ajustes, el modo copia u otro modal de Herdr, y plugin.pane.open devuelve un resultado ok tras lanzarla.

En Windows, los comandos de construcción, de acción y de evento resuelven los envoltorios habituales de PATHEXT, como npm.cmd, bun.cmd y pnpm.cmd, cuando el comando a secas está en el PATH. Los comandos de panel usan el lanzador normal de paneles de Windows y deben seguir siendo comandos argv válidos en Windows.

Atajos de teclado

Asigna una tecla a una acción de un plugin instalado:

[[keys.command]]
key = "prefix+l"
type = "plugin_action"
command = "example.layout.apply"
description = "apply layout"

Manejadores de enlaces

Usa [[link_handlers]] para desviar los clics con modificador sobre las URL de la terminal que coincidan hacia una acción del plugin, en vez de abrir la URL en el navegador. El modificador del clic es Control en todas las plataformas, macOS incluido, porque los informes de ratón capturados de la terminal no distinguen Comando/Super de un clic normal. pattern es una expresión regular de Rust que se compara con la URL pulsada, y action debe nombrar una acción declarada por el mismo plugin. Las acciones de los manejadores de enlaces reciben invocation_source = "link_click", clicked_url y link_handler_id en HERDR_PLUGIN_CONTEXT_JSON; los plugins de shell también pueden leer HERDR_PLUGIN_CLICKED_URL y HERDR_PLUGIN_LINK_HANDLER_ID. Los manejadores se comprueban en el orden del manifiesto dentro de cada plugin.

Almacenamiento

En la v1 no hay una API de almacenamiento de plugins gestionada por Herdr. Los plugins que necesiten estado duradero deben gestionar sus propios ficheros o base de datos.

Catálogo de plugins

Los plugins de la comunidad se pueden descubrir en el catálogo, un índice automático de repositorios públicos de GitHub etiquetados con herdr-plugin que contienen uno o más ficheros herdr-plugin.toml cuyos metadatos obligatorios se pueden leer. Los plugins siguen siendo repositorios normales de GitHub: publica uno y comparte herdr plugin install owner/repo[/subdir].

Para que tus plugins aparezcan, añade el topic de GitHub herdr-plugin y coloca sus manifiestos en la raíz o en subdirectorios de la rama por defecto del repositorio. Una misma tarjeta de repositorio puede contener varios plugins instalables por separado. El índice se refresca cada 30 minutos. Mira Catálogo de plugins para saber cómo funciona el descubrimiento.