Empaquetado y publicación | EmDash CMS Everything

Una vez que tu plugin sandbox funcione, publícalo para que otros sitios puedan instalarlo. La publicación es solo para sandbox — los plugins nativos se distribuyen a través de npm.

Cuando publicas, la CLI registra la versión en tu propia cuenta de Atmosphere. Tú alojas el tarball — como un asset de release de GitHub, R2, S3 o cualquier URL pública — y el registro almacena un enlace a él.

Requisitos previos

Un emdash-plugin.jsonc válido con slug, publisher, license, un autor (author o authors) y un contacto de seguridad (security o securityContacts). Ejecuta emdash-plugin validate para confirmar.
Una version (en package.json, o el manifest para plugins solo de registro).
Una cuenta de Atmosphere para publicar.

Tu cuenta de Atmosphere

Publicas bajo una cuenta de Atmosphere: una identidad portátil y propiedad del usuario utilizada en Bluesky y otras aplicaciones de la red AT Protocol. Una cuenta es tu único inicio de sesión en toda la red, con el mismo @handle en todas partes, y tu identidad y datos no están vinculados a ninguna aplicación. EmDash usa esta cuenta como tu identidad de publicador: cada versión que publicas es un registro en tu propia cuenta, firmado como tú.

EmDash usa las mismas cuentas de Atmosphere que su inicio de sesión de Atmosphere para sitios.

Usar una cuenta existente

Si ya tienes una cuenta de Bluesky o cualquier otra cuenta de Atmosphere, inicia sesión con su handle:

emdash-plugin login alice.bsky.social

Esto abre la página de inicio de sesión de tu proveedor de cuentas en el navegador. EmDash nunca ve tu contraseña. emdash-plugin whoami lista tus sesiones almacenadas; emdash-plugin switch <did> cambia la activa.

Registrarse para una cuenta

Si aún no tienes una cuenta de Atmosphere, crea una a través de cualquier proveedor, luego ejecuta emdash-plugin login <your-handle>. Tus opciones:

Una aplicación, como Bluesky. Registrarse en Bluesky crea una cuenta de Atmosphere alojada por Bluesky. Esta es la ruta más rápida.
Un proveedor independiente. Hosts de cuentas comunitarios o enfocados en privacidad. Explora opciones en atmosphereaccount.com.
Auto-alojado. Ejecuta tu propio proveedor para tener control total sobre tu identidad y datos.

Cualquiera que elijas, el @handle de esa cuenta es lo que pasas a emdash-plugin login, y el DID de la cuenta es lo que fijas como publisher en tu manifest.

Tres pasos

Los siguientes comandos inician sesión, construyen un tarball y publican una versión que apunta al tarball alojado:

emdash-plugin login                     # si aún no has iniciado sesión
emdash-plugin bundle                    # produce dist/<slug>-<version>.tar.gz
# sube ese tarball a una URL pública, luego:
emdash-plugin publish --url https://your-host/<slug>-<version>.tar.gz

bundle imprime los siguientes dos pasos cuando termina, incluyendo la invocación de --url, para que no tengas que recordar la forma.

Bundle

bundle ejecuta build, valida, recopila assets y crea un tarball. Dentro del tarball, plugin.mjs se empaqueta como backend.js (el nombre de archivo que espera el registro).

El comando acepta las siguientes flags:

emdash-plugin bundle [--dir <path>] [--out-dir|-o <path>] [--validate-only]

Flag	Predeterminado	Descripción
`--dir`	Directorio actual	Directorio fuente del plugin.
`--out-dir`, `-o`	`dist`	Directorio de salida para el tarball.
`--validate-only`	`false`	Omitir el tarball, pero aún producir artefactos de `dist/`.

Contenido del tarball

Archivo	Requerido	Descripción
`manifest.json`	Sí	Manifest generado: id, version, capabilities, hosts y los hooks y routes leídos de tu fuente. No lo mantienes a mano.
`backend.js`	Sí	El archivo de runtime construido y autocontenido (`dist/plugin.mjs`).
`README.md`	No	Documentación del plugin.
`icon.png`	No	PNG de 256×256.
`screenshots/`	No	Hasta 5, máximo 1920×1080.

Validación

bundle (y --validate-only) verifican:

Límites de tamaño (RFC 0001, descomprimido): total ≤ 256 KB, por archivo ≤ 128 KB, ≤ 20 archivos. El tarball comprimido con gzip es una fracción de eso.
Sin built-ins de Node en backend.js — el código sandbox no puede importar fs, path, child_process, etc. Usa Web APIs, o mueve esa lógica a un plugin nativo.
Cordura de capabilities — los nombres deben estar en el conjunto reconocido.
Coherencia del contrato de confianza — las reglas cruzadas de network:request / allowedHosts del manifest.
Límites de assets — icono 256×256, ≤ 5 capturas de pantalla en ≤ 1920×1080.

Para inspeccionar el tarball antes de publicar, lista su contenido:

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

Publish

La publicación escribe el registro de versión. El tarball ya debe estar alojado en una URL pública:

emdash-plugin publish --url <hosted-tarball-url>

--url es obligatorio: es donde viven los bytes del plugin, y el registro del registro apunta a él. Para verificar que la URL alojada sirve exactamente los bytes que construiste antes de escribir el registro, pasa --local:

emdash-plugin publish --url https://your-host/foo-1.0.0.tar.gz --local dist/foo-1.0.0.tar.gz

Lo que hace publish:

Obtiene el tarball en --url (con guardias de URL y tamaño) y extrae el manifest de esos bytes.
Reanuda tu sesión de cuenta de Atmosphere y verifica publisher pinning — la sesión activa debe coincidir con el publisher fijado del manifest, o se rechaza con MANIFEST_PUBLISHER_MISMATCH.
Crea el perfil del paquete a partir del manifest en la primera publicación (license, autor, contacto de seguridad). En publicaciones posteriores, gana el perfil existente.
Publica los registros de perfil y versión en tu cuenta.

En la primera publicación puedes proporcionar campos de perfil por flag (--license, --security-email, …) en lugar del manifest; las flags explícitas anulan los valores del manifest, lo cual es útil en CI. --no-manifest opta por no usar el manifest por completo.

Las versiones son inmutables

Una versión publicada no se puede sobrescribir ni volver a publicar. Incrementa version antes de volver a publicar. El build lee version de package.json (ver la referencia del manifest). Incrementa major para un contrato de confianza ampliado, minor para nuevos hooks o routes, y patch para correcciones.

Desajuste de publisher

Si publish falla con MANIFEST_PUBLISHER_MISMATCH, la sesión activa es una cuenta de Atmosphere diferente al publisher fijado del manifest. Cambia a la cuenta fijada con emdash-plugin switch <did>, o actualiza publisher en el manifest si genuinamente estás transfiriendo el plugin a una nueva cuenta. Ver Usar una cuenta existente para administrar sesiones.

Qué leer a continuación

La CLI de emdash-plugin — todos los comandos
El manifest — campos, contrato de confianza, publisher pinning
Capabilities y seguridad