Ecosistema y catálogo de plugins de WebBlocks

Este documento recoge la dirección del ecosistema de plugins de WebBlocks para la siguiente etapa, antes de que empiece la implementación. Es únicamente documentación de arquitectura. No añade código de ejecución, rutas, migraciones, controladores, clientes de API, tablas de base de datos, pantallas de administración, automatización de despliegue, etiquetas de versión ni incrementos de versión.

La arquitectura de plugins de WebBlocks debería abarcar todo el ecosistema, no solo el CMS. WebBlocks CMS es el primer anfitrión de plugins porque ya cuenta con los cimientos del sistema de plugins: definiciones respaldadas por un registro, carga e instalación manual de ZIP, plugins instalados desactivados por defecto, comprobaciones de compatibilidad y comportamiento inerte cuando están desactivados o son incompatibles. El mismo contrato debería poder reutilizarse en otros productos de WebBlocks cuando necesiten extensiones basadas en paquetes con una propiedad clara y reglas de ciclo de vida seguras.

Diseñar el contrato solo en torno al CMS dificultaría después compartir la identidad de los plugins, el empaquetado, la compatibilidad, los metadatos del catálogo y las reglas de seguridad. La dirección objetivo es un contrato de plugins de WebBlocks compartido que cada producto pueda alojar mediante sus propios puntos de extensión, preservando un modelo común de identidad, inspección de paquetes, compatibilidad, activación, actualizaciones y descubrimiento en el catálogo.

Los posibles anfitriones de plugins incluyen:

• WebBlocks CMS
• QuizTem
• Herne Panel
• WebBlocks Publisher
• futuros productos de WebBlocks

Cada producto anfitrión puede exponer puntos de extensión distintos. WebBlocks CMS expone menús de administración del CMS, rutas de plugin, permisos, ajustes, comandos, migraciones, bloques, recursos, comprobaciones de estado, widgets del panel y tarjetas del sistema. QuizTem, Herne Panel, WebBlocks Publisher y los futuros productos pueden exponer registros y pantallas propios distintos.

Aunque los puntos de extensión difieran, la identidad de los plugins, el empaquetado, la compatibilidad, el ciclo de vida y los metadatos del catálogo deberían seguir convenciones compartidas en todo el ecosistema de WebBlocks. Un plugin puede admitir un producto anfitrión o varios, pero la compatibilidad de producto siempre debe ser explícita e inspeccionable antes de la activación.

Todo plugin del ecosistema debería tener un handle estable:

• en kebab-case
• único a nivel global en todo el ecosistema de WebBlocks
• estable entre versiones
• usado como prefijo por defecto de rutas, permisos, ajustes, comandos, tablas, recursos e identidad del paquete

La propiedad basada en el prefijo del handle mantiene el comportamiento del plugin atribuible y a salvo de colisiones. Las rutas de administración, las rutas públicas, las cadenas de permiso, los espacios de nombres de ajustes, los nombres de comando, los prefijos de tablas de base de datos, los handles de recursos, los nombres de paquete, las rutas de artefactos y los registros del catálogo deberían poder rastrearse hasta el handle del plugin propietario.

La compatibilidad de producto debe ser explícita. Un plugin puede admitir solo WebBlocks CMS, solo QuizTem, solo Herne Panel, solo WebBlocks Publisher o una combinación admitida de productos anfitriones. Los productos anfitriones no admitidos deben tratar el plugin como incompatible e inerte.

El ecosistema debería avanzar hacia un concepto de manifiesto compartido que pueda inspeccionarse antes de la instalación y antes de la activación. La API concreta de implementación puede evolucionar, y los productos anfitriones pueden adaptar el manifiesto a registros específicos del producto, pero la propiedad y la compatibilidad deben seguir siendo inspeccionables antes de la activación.

Los metadatos del futuro manifiesto compartido deberían incluir:

• handle
• label
• vendor o author
• version
• los productos anfitriones admitidos
• las versiones requeridas del producto anfitrión
• las versiones requeridas de PHP y Laravel cuando proceda
• las clases de proveedor por producto anfitrión cuando sea necesario
• los permisos
• las aportaciones al menú de administración
• las declaraciones de rutas
• los comandos
• las migraciones
• los bloques o packs de bloques
• los recursos
• los ajustes
• las comprobaciones de estado
• las notas de la versión
• los metadatos de checksum y firma

El manifiesto debería permitir que un anfitrión responda a preguntas de seguridad antes de activar código: qué productos admite el paquete, qué versiones de producto se requieren, qué proveedores pueden arrancar, qué rutas y comandos se registrarían, qué permisos se crearían, qué tablas y espacios de nombres de ajustes son de su propiedad, qué migraciones pueden ofrecerse para una configuración explícita y qué artefactos se pueden verificar.

plugins.webblocksui.com es la superficie de catálogo/tienda propuesta para el futuro. Este documento no implica que el dominio exista, esté desplegado o esté en funcionamiento.

Los términos deberían mantenerse diferenciados:

• Plugin Catalog: descubrimiento, metadatos, compatibilidad, documentación, capturas de pantalla, enlaces de soporte, metadatos de versión, estado de seguridad y enlaces de descarga.
• Plugin Store: integración posterior de instalación/actualización desde metadatos de catálogo de confianza hacia un producto anfitrión.
• Marketplace: funciones comerciales futuras como cuentas, licencias, plugins de pago, reseñas, flujos de aprobación, perfiles de editor y flujos de ingresos.

El primer hito debería ser un Plugin Catalog, no un Marketplace comercial completo. Un catálogo puede establecer el contrato de metadatos, la matriz de compatibilidad, los checksums de los artefactos, los enlaces de documentación y una ruta de descarga manual segura sin añadir instalación remota, actualizaciones automáticas, licencias de pago ni flujos de aprobación comercial.

Para el posicionamiento del producto, el alcance del MVP, los modelos de implementación candidatos, las superficies del sitio web público, los conceptos de operador y la planificación de la API del producto de catálogo propuesto, consulte Plugin Catalog Product Architecture.

1. Fase 1: documentación y contrato de metadatos.
2. Fase 2: planificación del servidor y del modelo de datos del catálogo para plugins.webblocksui.com.
3. Fase 3: interfaz de solo lectura Browse Plugin Catalog en la administración del CMS. Implementada como /webadmin/plugins/catalog, usando WEBBLOCKS_PLUGIN_CATALOG_BASE_URL / webblocks-plugins.catalog.base_url y con https://plugins.webblocksui.com por defecto.
4. Fase 4: flujo de descarga/instalación manual de ZIP enlazado desde los metadatos del catálogo.
5. Fase 5: flujo controlado Install from Catalog, que sigue quedando desactivado por defecto tras la instalación.
6. Fase 6: comprobación de actualizaciones de plugin y disponibilidad de actualizaciones. Implementada para System -> Plugins -> Registered Plugins del CMS cuando los handles de plugin instalados tienen versiones de catálogo más recientes y compatibles con metadatos de artefacto completos.
7. Fase 7: flujo controlado de aplicación de actualizaciones de plugin. Implementado como una acción POST de super-admin que reutiliza la verificación de checksum del catálogo y la validación del ZIP del plugin, preservando el estado del ciclo de vida y dejando las migraciones explícitas.
8. Fase 8: funciones de marketplace, licencias y comerciales.

Cada fase debe preservar la instalación desactivada por defecto, el comportamiento que antepone la compatibilidad y las acciones explícitas de configuración o migración. Los metadatos remotos pueden ayudar a descubrir, evaluar, instalar o actualizar explícitamente plugins, pero no deben activar plugins en silencio, ejecutar migraciones, aplicar actualizaciones ni eludir las reglas de compatibilidad del producto anfitrión.

El navegador de catálogo del CMS lista los plugins públicos del catálogo compatibles con WebBlocks CMS y los metadatos de la última versión compatible. El CMS cuenta ahora con acciones explícitas de instalación/actualización desde el catálogo para super-admin sobre artefactos ZIP de confianza con metadatos de checksum completos, pero la navegación por el catálogo en sí no instala paquetes de Composer, ni activa plugins, ni ejecuta migraciones, ni registra rutas, comandos, proveedores o permisos, ni activa el estado de un plugin a partir de datos remotos.

Que el catálogo o la tienda no estén disponibles no debe impedir la gestión de los plugins instalados. El listado de plugins instalados, los controles de activación/desactivación, las guías de configuración, el estado de salud y la desinstalación deben seguir funcionando a partir del estado local.

Los datos remotos del catálogo no deben activar plugins automáticamente. Los datos remotos del catálogo no deben ejecutar migraciones automáticamente. Los datos remotos del catálogo no deben aplicar actualizaciones automáticamente. Las actualizaciones basadas en el catálogo requieren una acción POST explícita de super-admin y metadatos de artefacto de confianza. La instalación automática y arbitraria con Composer queda fuera del alcance salvo que una decisión de arquitectura futura la apruebe explícitamente.

Los artefactos ZIP deben verificarse antes de la instalación. La verificación debería bloquear el path traversal, los archivos de metadatos ocultos, el escape de la raíz, las sorpresas ejecutables en público, las colisiones de rutas, las colisiones de permisos, las colisiones de prefijos de tabla, las colisiones de límites entre productos anfitriones, los escapes por enlace simbólico, los destinos de instalación prohibidos, los manifiestos mal formados, los productos anfitriones incompatibles y las discrepancias de checksum o de futuras firmas.

Los plugins incompatibles, desactivados, con archivos ausentes o inseguros deben permanecer inertes. No deben registrar rutas, comandos, menús, permisos, rutas de ajustes, migraciones, trabajos programados, bloques, recursos, widgets, reporteros de estado ni ningún otro comportamiento activo en tiempo de ejecución.

La desinstalación sigue siendo «desactivar primero» y propiedad del almacenamiento. Una desinstalación ordinaria solo debe eliminar el directorio del paquete del plugin que reside en el almacenamiento y los registros locales del estado de activación. No debe eliminar las tablas de base de datos propiedad del plugin salvo que en el futuro se diseñe intencionadamente una herramienta de limpieza destructiva con confirmación explícita.

Sobrescribir las vistas del núcleo sigue estando prohibido por defecto. La extensión mediante plugins debe usar los registros documentados o los slots de extensión. Los plugins no deben sustituir las vistas del paquete, parchear servicios del producto sobre la marcha, añadir archivos de rutas ocultos ni depender de efectos secundarios arbitrarios de un include.

Los registros del Plugin Catalog deberían incluir:

• metadatos de ficha del plugin: handle, etiqueta, descripción, proveedor/autor, categorías, etiquetas, versión estable actual, URL de documentación, capturas de pantalla, URL de soporte y URL del código fuente o del gestor de incidencias cuando estén disponibles
• metadatos de versión: número de versión, fecha de publicación, notas de la versión, URL de los artefactos, checksums, futuras firmas, requisitos mínimos del anfitrión, notas de actualización y estado de obsolescencia
• metadatos de compatibilidad: productos anfitriones admitidos, restricciones de versión admitidas del producto anfitrión, versiones de PHP/Laravel requeridas cuando proceda, servicios de plataforma admitidos y requisitos de migración o configuración
• metadatos de avisos de seguridad y obsolescencia: versiones afectadas, versiones corregidas, gravedad, enlaces a los avisos, marcas de inseguridad, versiones obsoletas, orientación de sustitución y estado de bloqueo de instalación/actualización
• metadatos de verificación de artefactos: algoritmo de checksum, valor del checksum, tamaño del artefacto, datos de firma futuros, identidad de la clave de firma y estado de integridad
• URL de documentación, capturas de pantalla y soporte: documentación pública, registro de cambios, guía de configuración, capturas de pantalla, contacto de soporte, gestor de incidencias y perfil del proveedor
• matriz de compatibilidad de productos anfitriones: una fila por producto anfitrión admitido, con el handle del producto, su etiqueta, las restricciones de versión compatibles, los metadatos de la clase de proveedor cuando sean necesarios, los puntos de extensión usados, los requisitos de configuración y las limitaciones conocidas

Los metadatos del catálogo deberían ser útiles antes de la descarga, antes de la instalación, antes de la activación, antes de la configuración o migración y antes de aplicar una actualización.

El futuro Plugin Catalog puede reutilizar ideas del flujo actual de metadatos de actualización/publicación de WebBlocks Publisher, incluidos los metadatos de versión, los checksums de los artefactos, los manifiestos y los conceptos de distribución alojada. La publicación en el catálogo de plugins debería documentarse igualmente como una capacidad de producto aparte.

Este documento no presupone una implementación dentro del código actual de WebBlocks Publisher. plugins.webblocksui.com podrá funcionar más adelante sobre WebBlocks Publisher, sobre una aplicación de catálogo dedicada o sobre un sitio de WebBlocks CMS con un plugin de catálogo. La elección de implementación debería tomarse una vez que el contrato de metadatos del catálogo y el límite de producto estén claros.

Consulte Plugin System para conocer la arquitectura actual del anfitrión de plugins de WebBlocks CMS.

La carga e instalación manual de ZIP en el CMS sigue siendo el método de instalación de plugins admitido actualmente. Los plugins subidos se instalan en rutas del almacenamiento, permanecen desactivados por defecto y requieren acciones explícitas de activación y de configuración o migración. Los plugins desactivados e incompatibles permanecen inertes.

El trabajo de catálogo/tienda debería apoyarse en el ciclo de vida de plugins existente del CMS en lugar de sustituirlo. El futuro descubrimiento en el catálogo, los enlaces de descarga manual, los flujos de instalación desde el catálogo, las comprobaciones de actualización y las acciones controladas de aplicación de actualizaciones deberían reutilizar las mismas reglas de handle, compatibilidad, desactivación por defecto, configuración requerida, preparación del esquema, permisos, propiedad de rutas y seguridad en la desinstalación.

Esta fase no incluye:

• la implementación en tiempo de ejecución
• la instalación remota automática
• la aplicación automática de actualizaciones de plugin
• el comportamiento de marketplace de pago
• el comportamiento de un servidor de licencias
• el flujo de aprobación de terceros
• la automatización del despliegue en producción
• la verificación en el sitio en producción