Cockpit - Guía Operativa para Agentes IA

1) Propósito de este documento

Este archivo define el contexto técnico real del proyecto para que otro agente IA pueda trabajar con baja ambigüedad, respetando arquitectura, contratos y convenciones ya existentes.

Debe usarse como guía de implementación práctica, no como inspiración genérica.

2) Rol esperado del agente

Actúa como ingeniero de software senior en:

• React + TypeScript (frontend modular)
• Tauri 2 + Rust (bridge desktop/runtime)
• Arquitectura en capas y diseño orientado a extensibilidad por paquetes

Tu objetivo principal es extender el sistema mediante paquetes/módulos, siguiendo las directrices mencionadas debajo acerca de lo se que puede y no se puede cambiar.

No debes hacer código de compatibilidad ya que este proyecto está en etapa de desarrollo

Cuando termines de implementar un cambio haz npm run build y npm run test. No compiles para tauri

3) Frontera de cambio (crítico)

Esta sección define explícitamente qué cosas son inmutables (objetivo del producto) y qué cosas son evolutivas (implementación actual).

3.1) Lo que NO debe cambiar (inmutable)

1. Cockpit es un host modular para construir interfaces funcionales por extensión.
2. La extensión principal es por paquetes y módulos (src/packages/<packageId>), no por parches directos al shell.
3. El layout base tipo VSCode se conserva como contrato de producto:
   • sidebar
   • workspace
   • console
   • toolbar
   • footer
   • modal
4. Las funcionalidades nuevas deben entrar en esos contenedores.
5. La arquitectura es en capas y con comunicación entre capas adyacentes.

3.2) Lo que SÍ puede cambiar (evolutivo)

1. La estructura concreta de carpetas, nombres internos y composición de módulos.
2. Implementaciones de servicios, dispatchers, transports y componentes.
3. Contratos técnicos específicos de backend (op, payloads, timeouts), manteniendo compatibilidad cuando aplique.
4. Mecanismos de persistencia y configuración (siempre preservando la API pública de runtime o migrándola con criterio).
5. Detalles de UX, estilos y comportamiento de vistas.
6. Añadir/quitar capas para solucionar problemas que aparecen mas facilmente, solo si es necesario y ventajoso

3.3) Regla de decisión para agentes

Si una propuesta mejora un detalle técnico pero rompe los puntos de la sección 3.1, se rechaza.
Si respeta la sección 3.1 y mejora mantenibilidad/claridad/funcionalidad, es válida.

4) Enfoque del producto (no negociable)

Cockpit es un host modular con layout tipo VSCode:

• sidebar (panel lateral)
• workspace (vista central con tabs)
• console (consola con tabs)
• toolbar (menú superior)
• footer (estado inferior)
• modal (diálogos modales)

Las nuevas capacidades deben entrar en esos contenedores existentes.
No introducir nuevos “hosts” de UI como patrón principal salvo requerimiento explícito.

La forma de extensión es por paquetes (src/packages/<packageId>) y módulos dentro de cada paquete.

19) Definición de “bien hecho”

Un cambio está bien hecho si:

• Respeta el flujo por capas.
• Se integra vía paquete/módulo y contribuciones.
• Tiene pruebas proporcionales al riesgo.
• No introduce acoplamientos innecesarios al shell.