Instruction file imported from pere94/AgentMesh (.github/instructions/rules.instructions.md). Copyright stays with the author.

Instrucciones de desarrollo — AgentMesh

Contexto del proyecto

AgentMesh es un crawler e indexador de agentes de IA escrito en TypeScript, ejecutado con Bun como runtime. Descubre agentes mediante endpoints conocidos (.well-known/ai-agent.json), los indexa en Elasticsearch 8.x y los expone a través de una API HTTP construida con Hono. La validación de datos usa Zod v4.

Stack principal:

• Runtime: Bun (no Node.js)
• Lenguaje: TypeScript strict (tsconfig.json con strict: true, noUncheckedIndexedAccess, noImplicitOverride)
• API: Hono v4
• Base de datos: Elasticsearch 8.x (vía Docker)
• Validación: Zod v4
• Módulos: ESNext ESM ("type": "module")
• Resolución de módulos: modo bundler — permite importar con extensión .ts

Reglas de lenguaje y ficheros

• Todo el código fuente debe estar en TypeScript (.ts). No generar .js salvo integración con herramienta externa que lo exija; documentarlo en la descripción del PR.
• Usar la extensión .ts explícitamente en las importaciones locales: import { foo } from './foo.ts' (no './foo' ni './foo.js').
• No generar artefactos compilados (dist/, build/, .js en src/).

Convenciones de TypeScript

• Respetar la configuración de tsconfig.json: target ESNext, strict, verbatimModuleSyntax, noUncheckedIndexedAccess.
• Usar type para importaciones de solo tipos: import type { Foo } from './foo.ts'.
• Evitar any; tipar explícitamente los datos externos (respuestas de Elasticsearch, fetch, etc.) o usar unknown y validar con Zod.
• Preferir const sobre let; evitar var.
• async/await siempre sobre callbacks o .then() encadenado.
• Para scripts ejecutables, usar import.meta.main como guarda de entrada (patrón Bun): if ((import.meta as any).main) { ... }.

Bun — uso del runtime

• Usar las APIs nativas de Bun cuando estén disponibles y sean superiores a las de Node.js (Bun.file, Bun.write, Bun.serve, etc.).
• Para leer archivos de texto pequeños preferir Bun.file(...).text() sobre fs.readFile.
• No instalar polyfills de Node.js para funcionalidades ya cubiertas por Bun.
• Los scripts se ejecutan con bun run <archivo>.ts; no hace falta paso de compilación.

Hono — API HTTP

• Definir rutas en src/api/; exportar el Hono app desde un index.ts de módulo.
• Usar el middleware de validación de Hono con esquemas Zod para validar body, query params y path params en los endpoints.
• Devolver errores con los helpers de Hono (c.json({ error: '...' }, 400)) y códigos HTTP semánticos.
• No exponer stack traces ni mensajes internos de Elasticsearch en respuestas HTTP de producción.

Zod — validación

• Definir todos los schemas de datos en src/schemas/.
• Usar z.parse() para validación estricta en entrada de datos externos; usar z.safeParse() cuando se quiere manejar el error sin lanzar excepción.
• Inferir tipos desde los schemas con z.infer<typeof Schema> en lugar de duplicar interfaces TypeScript.

Elasticsearch

• Toda interacción con Elasticsearch debe pasar por el cliente de @elastic/elasticsearch.
• Leer la URL del nodo desde variables de entorno: process.env.ELASTIC_URL ?? 'http://localhost:9200'.
• Los índices y mappings se definen en src/indexer/; no hardcodear nombres de índice en módulos de API o crawler.
• En desarrollo, es aceptable borrar y recrear índices al iniciar; en producción usar migraciones o alias.

Variables de entorno

• Cargar con dotenv al inicio del proceso principal (dotenv.config()).
• Acceder siempre con process.env.VAR ?? 'valor_por_defecto'; nunca asumir que la variable existe sin comprobarlo.
• No comitear ficheros .env con credenciales reales; añadirlos a .gitignore.

Gestión de errores

• En scripts y workers, capturar errores en el nivel más alto y registrarlos con console.error; salir con process.exit(1) si el error es fatal.
• En la API, usar middleware de error de Hono para respuestas consistentes.
• Para operaciones de fetch, manejar timeout con AbortController (patrón ya establecido en engine.ts).

Estructura de módulos

src/
  api/          # Rutas y middleware Hono
  crawler/      # Lógica de descubrimiento de agentes
  indexer/      # Setup y operaciones de Elasticsearch
  schemas/      # Schemas Zod compartidos

• Cada directorio expone sus funciones públicas desde un index.ts cuando tiene más de un fichero.
• No cruzar dependencias en sentido contrario: api puede usar schemas e indexer; crawler no debe importar desde api.

Checklist antes de abrir un PR

1. Todos los ficheros fuente nuevos usan .ts y las importaciones locales incluyen la extensión .ts.
2. No se han generado artefactos compilados en src/ o dist/.
3. Las variables de entorno nuevas están documentadas en el README o en un .env.example.
4. Los tipos any añadidos están justificados con un comentario.
5. Cualquier fichero .js de excepción está explicado en la descripción del PR.

Última actualización: marzo 2026