Empaquetar y publicar

Una vez que tu plugin de sandbox funcione, puedes publicarlo en el marketplace de EmDash para que otros sitios puedan instalarlo con un clic desde el panel de administración. El flujo de publicación es solo para sandbox: los plugins nativos se distribuyen a través de npm y no se empaquetan en tarballs del marketplace.

Requisitos previos

Antes de publicar, asegúrate de que tu plugin:

• Tiene un package.json con una exportación "." (el descriptor) y una exportación "./sandbox" (el punto de entrada del runtime).
• Usa format: "standard" en el descriptor.
• Tiene un id único y una version semver válida.
• Declara sus capabilities y allowedHosts con precisión en el descriptor.

Formato del paquete

Los plugins publicados se distribuyen como tarballs .tar.gz que contienen:

manifest.json se genera automáticamente. Contiene el id del plugin, versión, capabilities, hosts permitidos, nombres de hooks, nombres de rutas y configuración de admin, pero sin código ejecutable.

Construir un paquete

cd packages/plugins/my-plugin
emdash plugin bundle

Esto hará:

Resolución de puntos de entrada

El comando bundle encuentra tu código a través de las exportaciones de package.json:

{
	"exports": {
		".": { "import": "./dist/index.mjs" },
		"./sandbox": { "import": "./dist/sandbox-entry.mjs" },
		"./admin": { "import": "./dist/admin.mjs" }
	}
}

Si falta "./sandbox", el comando busca src/sandbox-entry.ts como alternativa. El empaquetador mapea rutas dist de vuelta al código fuente automáticamente: si tu exportación "." apunta a ./dist/index.mjs, encontrará y construirá src/index.ts.

Opciones

emdash plugin bundle [--dir <path>] [--outDir <path>]

Validación

El comando bundle verifica:

• Límite de tamaño — el paquete total debe ser menor de 5 MB.
• Sin built-ins de Node.js en backend.js — el código sandbox no puede importar fs, path, child_process, etc. Reemplázalos con Web APIs o mueve la lógica a un plugin nativo.
• Lista blanca de capabilities — las capabilities declaradas deben estar en el conjunto conocido (errores tipográficos fallan).
• Nombres de capability obsoletos activan advertencias aquí y un fallo duro en tiempo de publicación.
• network:request sin allowedHosts activa una advertencia (considera network:request:unrestricted si los hosts se configuran por el operador en runtime, o lista los hosts explícitamente).
• Dimensiones del icono — icon.png debe ser 256×256 (advierte si es incorrecto; aún así lo incluye).
• Límites de capturas de pantalla — máximo 5 capturas de pantalla, máximo 1920×1080.

Publicar

emdash plugin publish

Esto encuentra el .tar.gz más reciente en dist/ y lo sube. Para ser explícito sobre el tarball o para construir antes de publicar:

# Ruta de tarball explícita
emdash plugin publish --tarball dist/my-plugin-1.0.0.tar.gz

# Construir primero, luego publicar
emdash plugin publish --build

Autenticación

La primera vez que publiques, la CLI te autentica a través de GitHub:

El token dura 30 días. Después de que expire, se te pedirá que vuelvas a autenticarte en la próxima publicación.

Puedes gestionar la autenticación por separado:

emdash plugin login    # iniciar sesión sin publicar
emdash plugin logout   # borrar token almacenado

Registro por primera vez

Si tu id de plugin aún no es conocido por el marketplace, emdash plugin publish lo registra automáticamente antes de subir la primera versión.

Requisitos de versión

Cada versión publicada debe tener una semver más alta que la última. No puedes sobrescribir o volver a publicar una versión existente: aumenta la versión tanto en package.json como en el descriptor antes de publicar nuevamente.

Auditoría de seguridad

Cada versión publicada pasa por una auditoría de seguridad automatizada. La auditoría escanea backend.js y admin.js en busca de:

• Patrones de exfiltración de datos
• Recolección de credenciales a través de configuraciones
• Código ofuscado
• Abuso de recursos (minería de criptomonedas, etc.)
• Actividad de red sospechosa

La auditoría produce un veredicto de pass, warn o fail, mostrado en la lista del marketplace del plugin. Dependiendo del nivel de aplicación del marketplace, un veredicto de fail puede bloquear completamente la publicación.

Opciones

emdash plugin publish [--tarball <path>] [--build] [--dir <path>] [--registry <url>]

Flujo completo

Ciclo de publicación típico:

# 1. Haz tus cambios
# 2. Aumenta la versión en src/index.ts y package.json
# 3. Empaqueta y publica
emdash plugin publish --build

Si quieres inspeccionar el paquete primero:

emdash plugin bundle
tar tzf dist/my-plugin-1.1.0.tar.gz
emdash plugin publish