Kit de plugins (hury-plugin)

@hury/plugin-kit es un paquete npm con el binario hury-plugin. Requiere Node.js 22 o superior. No tiene dependencias de ejecución propias salvo esbuild y vite (con @vitejs/plugin-vue, vue y vue-router), que usa para compilar.

curl -O https://developer.hury.es/downloads/hury-plugin-kit-0.1.0.tgz
npm install -g ./hury-plugin-kit-0.1.0.tgz
hury-plugin --help

La huella SHA-256 de cada descarga está en Descargas.

Comandos

Comando	Qué hace
init <clave>	Crea el proyecto desde la plantilla. Opciones: --title, --author, --dir, --kit
build	Compila la API (esbuild) y el panel (Vite, ESM) como la herramienta interna de Hury, y genera dist/<clave>-<versión>.zip con plugin.json y checksums.json, sin firmar. Opciones: --out, --bump
keygen	Crea un par Ed25519 e imprime la clave pública en el formato de PLUGIN_TRUSTED_KEYS. Opción: --out
sign <zip>	Firma el zip con tu clave y escribe plugin.sig. Opciones: --key, --out
verify <zip>	Comprueba firma, huellas, plugin.json y apiVersion, igual que el instalador. Opciones: --key, --unsigned, --api-version
pubkey	Imprime la clave pública y su huella. Opción: --key

init

hury-plugin init notas --title Notas --author "Mi empresa"

• <clave>: camelCase, 2 a 40 caracteres, empieza por minúscula (/^[a-z][a-zA-Z0-9]{1,39}$/).
• --title: nombre visible (por defecto, derivado de la clave). --author: autor en el Marketplace.
• --dir: carpeta de destino (por defecto ./<clave>; debe no existir o estar vacía).
• --kit: de dónde instalar @hury/plugin-kit en el proyecto (URL, ruta file: o nombre en npm). Por defecto, la descarga de este portal.

build

Falla si tu código importa algo que el host no expone (la lista está en host de la API y admin) o usa import * as del host. El paquete no incluye las librerías del host.

keygen, sign, pubkey

• La clave privada se guarda en ~/.hury/dev-plugin-signing.pem con permisos 600. keygen no la sobrescribe nunca: si ya existe, muestra la pública de la existente.
• sign y pubkey aceptan --key <fichero> o la variable HURY_PLUGIN_SIGNING_KEY con el PEM (para CI).
• Huella de una clave: los 8 primeros caracteres hexadecimales del SHA-256 de la clave pública en DER (SPKI). Es la misma que verá el dueño de la instalación.

verify

hury-plugin verify dist/notas-1.1.0.zip --key "$(hury-plugin pubkey)"

--key acepta un fichero, un PEM o una clave en base64; varias, separadas por comas. Sin --key usa PLUGIN_TRUSTED_KEYS o PLUGIN_PUBLIC_KEY del entorno. --unsigned admite un paquete aún sin firmar (solo estructura y huellas). Código de salida 0 solo si todo es válido.

Tipos del host

El kit incluye types/host y types/admin: declaraciones .d.ts emitidas por el compilador de TypeScript desde el código real de la API y del panel de la demo. La plantilla las usa con paths (@host/*, @/*) en su tsconfig. Que un tipo exista no implica que el host entregue ese módulo en tiempo de ejecución: lo que se puede importar es lo que enumera host-index.json del kit (generado de hostRegistry.ts y runtime.ts), y build falla si fuera de esa lista. Los módulos externos que referencian los tipos del host (stripe, pg…) no se instalan y quedan como any.

Pruebas: @hury/plugin-kit/testing

Compila tu API con el mismo esbuild que build, la carga con un host de pruebas y la monta en un Fastify real con una base de datos Kysely falsa que no abre conexiones:

Función	Para qué
createHostMock(dir, overrides?)	Host de pruebas con lo mínimo que usa la plantilla; overrides añade o sustituye módulos
loadPluginApi(dir, host?)	Compila y carga tu API; devuelve el ZModule
createFakeDb(kysely, answer?)	Base de datos falsa: registra el SQL en queries y devuelve las filas que le indiques
createTestApp({ module, db, host })	Fastify con tus rutas; identidad por la cabecera x-test-permissions: a.view,a.edit (o x-test-admin: 1)
projectRequire(dir)	require desde tu proyecto (kysely, zod, fastify)

Es un doble de pruebas, no el host: cubre rutas, validación, permisos y consultas emitidas. Las migraciones y el comportamiento real de PostgreSQL se comprueban instalando el plugin en una instalación de pruebas. Un ejemplo con tareas, eventos y ganchos: paso 7 de la guía.