Desarrollo de módulos
Amplía IWE Code con módulos externos. Empaqueta un programa, describe su panel en JSON e instálalo desde un archivo.
Un módulo externo es un programa independiente que IWE Code ejecuta y con el que se comunica mediante un protocolo JSON sencillo. Escríbelo en cualquier lenguaje, adjunta binarios para tus plataformas e instala el paquete sin recompilar la aplicación.
Cómo funciona
- Tu módulo se ejecuta como un proceso propio. IWE Code lo inicia al activar el módulo y lo detiene al desactivarlo o quitarlo.
- El anfitrión y el módulo intercambian un documento JSON por línea a través de la entrada y salida estándar del proceso.
- El módulo describe su panel con un árbol de widgets declarativo. IWE Code lo dibuja con sus propios componentes nativos.
- El módulo localiza el texto de su propio panel. El anfitrión informa del idioma de la interfaz al arrancar.
El manifiesto
Cada paquete contiene un archivo manifest.json que describe el módulo.
id- Identificador único en kebab-case en minúsculas, por ejemplo hello-module.
name, description- Textos localizados. El inglés es obligatorio; el ruso y el español son opcionales.
version- Versión semántica del módulo. Las actualizaciones deben aumentarla.
api- Versión del protocolo. La versión actual es 1.
minAppVersion- Versión mínima de la aplicación que admite el módulo.
entry- Nombre del ejecutable por destino de plataforma, por ejemplo macos-aarch64.
permissions- Acceso declarado: filesystem-read, filesystem-write, network, process.
placement- Zona del espacio de trabajo para el panel: header, top, left, right o bottom.
{
"id": "hello-module",
"name": { "en": "Hello module", "ru": "Модуль приветствия" },
"description": { "en": "Shows a friendly panel." },
"version": "1.0.0",
"api": 1,
"minAppVersion": "1.0.8",
"entry": { "macos-aarch64": "hello-module", "linux-x86_64": "hello-module" },
"permissions": [],
"placement": "bottom"
}Estructura del paquete
Un paquete es un archivo tar comprimido con gzip y extensión .iwe-module.
hello-module/
├── manifest.json
├── manifest.sig
└── binaries/
├── macos-aarch64/hello-module
└── linux-x86_64/hello-moduleMensajes del protocolo
Cada mensaje es una línea JSON. Los mensajes desconocidos se ignoran, así que los módulos pueden ser sencillos.
{"type":"initialize","api":1,"appVersion":"1.0.8","language":"en","installPath":"/…/modules/hello-module/1.0.0"}
{"type":"panel","content":{"type":"column","children":[{"type":"text","content":"Hello!"}]}}
{"type":"event","id":"click","action":{"type":"click"}}
{"type":"notify","level":"info","message":"Done"}
{"type":"shutdown"}De IWE Code al módulo
initialize- Se envía una vez al arrancar. Informa de la versión del protocolo, la de la aplicación, el idioma de la interfaz y la ruta de instalación.
event- Informa de una interacción con un widget: un clic, un cambio de estado o de texto.
shutdown- Pide al módulo que termine.
Del módulo a IWE Code
panel- Sustituye el contenido del panel por un nuevo árbol de widgets.
notify- Muestra un mensaje breve con nivel info, warning o error.
Widgets del panel
Un panel es un árbol de nodos simples. Cada nodo tiene un tipo y sus propios campos.
column, row- Apilan nodos hijos en vertical o en horizontal con un espaciado opcional.
text- Muestra texto con estilo body, heading, caption, muted o danger.
button- Un botón con etiqueta que informa del clic. Estilos: primary, secondary, danger.
text-input- Un campo de una línea que informa de los cambios de valor.
checkbox, toggle- Controles booleanos que informan de su nuevo estado.
progress- Una barra de progreso entre 0 y 1.
separator, scroll, spacer- Ayudas de diseño para dividir, desplazar y llenar espacio.
Permisos
El manifiesto declara el acceso que necesita el módulo. IWE Code muestra esta lista antes de la instalación y pide confirmación. Los módulos se ejecutan con los permisos de tu usuario; IWE Code no los aísla. Instala solo módulos de confianza.
filesystem-read- Leer archivos de tu equipo.
filesystem-write- Cambiar archivos de tu equipo.
network- Acceder a la red.
process- Iniciar otros programas.
Compila un paquete
Compila el módulo de referencia, monta la carpeta del paquete y comprímela. El ejemplo es un módulo completo en Rust que puedes copiar.
cargo build --release --example hello-module mkdir -p hello-module/binaries/macos-aarch64 cp target/release/examples/hello-module hello-module/binaries/macos-aarch64/ cp manifest.json hello-module/ tar -czf hello-module.iwe-module -C hello-module manifest.json binaries
Firma del paquete
IWE Code verifica las firmas y las sumas de los archivos. Rechaza paquetes modificados o sin firma.
El script de firma requiere la clave Ed25519 del responsable. Consulta la referencia de paquetes.
python3 .github/scripts/sign-module.py hello-module.iwe-module
Instalación
Abre Ajustes → Módulos en IWE Code, elige Instalar desde archivo…, revisa el acceso solicitado y confirma. Las actualizaciones se instalan igual con un número de versión mayor.
Módulo de referencia
El repositorio contiene un ejemplo funcional en examples/hello-module.