Ciclo de vida

Estados de un módulo

Estado	Qué significa
No instalado	No hay código ni tablas. La clave figura como bloqueada not_installed.
Instalado y apagado	El plugin está cargado, pero su interruptor está apagado: sus rutas responden 404 MODULE_DISABLED, el panel no importa su código y sus tareas periódicas se saltan.
Activo	El interruptor está encendido: rutas, menú, tareas y permisos operativos.
Bloqueado	El interruptor puede estar encendido, pero la API lo ve apagado (not_installed, o unlicensed con licencias exigidas).

El interruptor se cambia en Ajustes → Módulos (POST /modules/:key/enable, PUT /settings/features). defaultEnabled del manifiesto fija el estado inicial en una instalación que nunca lo ha tocado.

Instalar, actualizar, volver atrás

• Instalar: desde el catálogo, o subiendo un .zip en Ajustes → Módulos. Requiere que la firma sea de una clave aceptada por la instalación. Escritura: permiso settings.edit.
• Actualizar: subir un .zip con una versión mayor. Pesa unas decenas de KB y solo hay que esperar el reinicio de la API y el worker; no hace falta reconstruir la imagen ni redesplegar el panel.
• Versión anterior: POST /plugins/:key/rollback. Se vuelve al código anterior; las migraciones no se deshacen, por eso deben ser compatibles hacia atrás.
• Reinicio: cada cambio de plugin_installs lo detecta el vigilante (15 s) y reinicia la API y el worker.

Migraciones

• Ficheros migrations/*.sql, en orden alfabético (001_…, 002_…). Cada una corre en su transacción y se anota en plugin_migrations; solo corren las que no constan.
• Las sentencias se separan por ; a final de línea. No uses ; al final de línea dentro de una función o de un literal. La última puede ir sin ;.
• Idempotentes (CREATE TABLE IF NOT EXISTS, ALTER TABLE … ADD COLUMN IF NOT EXISTS, INSERT … WHERE NOT EXISTS) y compatibles hacia atrás.
• Una versión nueva con esquema nuevo añade 002_….sql; nunca edites una migración que ya salió.
• Las tablas de otro módulo no se alteran desde un plugin; si hace falta una columna del núcleo, es un cambio del host.

Desinstalar

Como en WordPress, desinstalar quita el código y deja los datos: tablas, permisos concedidos y ajustes se conservan, y reinstalar los recupera.

Desinstalar y borrar datos

Es una acción aparte, irreversible y con doble confirmación en el panel (la primera lista las tablas que se borrarán).

• API: DELETE /plugins/:key?purge=1 y DELETE /plugins?purge=1 (todos, en una sola transacción). GET /plugins/data-preview[?key=] muestra qué se borraría, sin borrar. Exige settings.edit y se audita como plugin.purged con las tablas.
• Qué borra: las tablas que el plugin crea en sus migrations/*.sql (los CREATE TABLE) y su historial de migraciones. No borra columnas que añadió a tablas del núcleo, ni permisos, ajustes ni ficheros subidos.
• Seguridad: DROP TABLE sin CASCADE, en una sentencia y en la misma transacción que quitar el plugin. Si una tabla de otro plugin depende de las suyas, falla sin borrar nada. Las claves foráneas desde tablas del núcleo se sueltan y la migración del plugin las recrea al reinstalar. Si no se encuentran las migraciones en el servidor, aborta en lugar de dar los datos por borrados. No se pueden borrar los datos de un plugin que otro necesita.
• Orfandad: los datos de un plugin desinstalado SIN borrar no se pueden borrar después sin reinstalarlo (se necesita su carpeta). Reinstálalo y bórralo.

Consecuencia para quien escribe un plugin: diseña tus migraciones pensando en que alguien puede pedir borrar tus tablas. No metas en ellas datos que no sean del plugin.

Endpoints

GET /plugins · GET /plugins/runtime (sesión) · POST /plugins/install (multipart file) · POST /plugins/install-from-catalog · POST /plugins/:key/rollback · DELETE /plugins/:key · GET /plugins/assets/:key/:versión/*. Escritura: settings.edit.

Variables de la instalación

Variable	Para qué
PLUGINS_DIR	Dónde se extraen los paquetes (/app/plugins, volumen ./plugins)
PLUGIN_PUBLIC_KEY	Clave pública Ed25519 de Hury (PEM o PEM en base64)
PLUGIN_TRUSTED_KEYS	Claves públicas adicionales de confianza (decisión del dueño de la instalación). Ver Confiar en una clave
PLUGIN_LICENSE_PUBLIC_KEY	Clave pública de licencias (la de Studio)
PLUGINS_REVOCATION_URL	Lista firmada de licencias revocadas (https)
PLUGINS_CATALOG_URL	Catálogo opcional
PLUGINS_LICENSE	off (por defecto) o required