Documentación

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-module

Mensajes 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.

Referencia completa