Skip to content

🛠️ Tools: Unidades de Orquestación ​

Las herramientas (Tools) son las piezas que contienen la lógica de negocio en Firefly JS. Su misión es orquestar las capacidades de los plugins para realizar acciones concretas.

🏗️ Anatomía de una Tool ​

Una Tool es una clase que implementa la interfaz FireflyTool.

ts
import { FireflyTool, Kernel } from '@fireflyjs/core'

export class MiTool implements FireflyTool {
  readonly name = "identificador-de-mi-tool"
  readonly mode = "run" // O "watch"

  async run(kernel: Kernel): Promise<void> {
    // 1. Obtener plugins necesarios del Kernel
    // 2. Ejecutar lógica combinando datos
    // 3. Emitir resultados o excepciones
  }
}

🚀 Ejecución Secuencial y Reactiva ​

El Kernel ejecuta las herramientas de forma secuencial. Esto garantiza que si una tool depende del resultado de otra, el sistema respetará ese orden.

🧩 Orquestación de Capacidades ​

Una tool no debería realizar tareas de bajo nivel (como leer archivos directamente). En su lugar, debe solicitar esa capacidad al Kernel:

ts
async run(kernel: Kernel) {
  const reader = kernel.getPlugin<FileReaderPlugin>("fireflyjs-plugin-file-reader");
  const workspace = reader.process(); // Capacidad del plugin
  
  // La tool decide qué hacer con el árbol (lógica de negocio)
  this.analizarEstructura(workspace);
}

🛠️ Modos de Ejecución ​

ModoComportamiento del Kernel
runTareas de "un solo disparo". Cuando el método run() termina, el Kernel ejecuta el shutdown y el proceso finaliza. Ideal para CI/CD.
watchTareas continuas. El Kernel permanece en memoria tras ejecutar run(), permitiendo que la Tool reaccione a eventos emitidos por los Drivers.

💡 Recomendaciones de Diseño ​

  • Inyección por Nombre: Evita importar tipos de plugins de forma estática si es posible. Pide los plugins al Kernel por su nombre configurado.
  • Salida Limpia: Las herramientas son responsables de la interfaz con el usuario (consola, logs, notificaciones).
  • Fallar Rápido: Si una tool detecta una violación crítica, debe lanzar una excepción o emitir un evento de error para que el Kernel actúe en consecuencia.