Empaquetar y publicar | EmDash CMS Everything

Publica un plugin sandboxed que funcione para que otros sitios puedan instalarlo. La publicación es solo para plugins sandboxed: los plugins nativos se distribuyen mediante npm.

Publica directamente desde la CLI, o usa el servicio de publicaciones automatizadas para compilar y publicar desde GitHub Actions. Ambos caminos escriben la publicación en tu cuenta Atmosphere. Solo necesitas un host de artefactos aparte cuando eliges explícitamente la ruta --url de la CLI directa.

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 confirmarlo.
Una version (en package.json, o en el manifiesto para plugins que solo existen en el registro).
Una cuenta Atmosphere con la que publicar.

Elegir un método de publicación

Ambos métodos crean registros de paquete y de publicación que pertenecen al publisher. Elige dónde debe ejecutarse la compilación de la publicación y qué credencial debe autorizarla.

Método	Úsalo cuando	Acceso a la cuenta
`emdash-plugin publish`	Compilas y publicas desde tu ordenador o desde otro entorno de confianza.	La sesión local de la CLI escribe el perfil del paquete, la publicación y los blobs.
Publicaciones automatizadas	GitHub Actions debe compilar publicaciones a partir de etiquetas de versión o ejecuciones manuales del flujo de trabajo.	La CLI local prepara el perfil; el servicio de publicaciones conserva únicamente la autoridad para crear publicaciones y blobs.

Tu cuenta Atmosphere

Publicas con una cuenta Atmosphere: una identidad portátil y propiedad del usuario que se usa en Bluesky y en 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 tus datos no están ligados a ninguna aplicación concreta. EmDash usa esta cuenta como tu identidad de publisher: cada publicación que haces es un registro en tu propia cuenta, firmado como tú.

EmDash usa las mismas cuentas Atmosphere para el inicio de sesión con Atmosphere de los sitios.

Usar una cuenta existente

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

emdash-plugin login alice.bsky.social

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

Crear una cuenta

Si todavía no tienes una cuenta Atmosphere, crea una con cualquier proveedor y luego ejecuta emdash-plugin login <your-handle>. Tus opciones:

Una aplicación, como Bluesky. Registrarte en Bluesky crea una cuenta Atmosphere alojada por Bluesky. Es la vía más rápida.
Un proveedor independiente. Alojamientos de cuentas gestionados por la comunidad o centrados en la privacidad. Consulta las opciones en atmosphereaccount.com.
Autoalojado. Ejecuta tu propio proveedor para tener control total sobre tu identidad y tus datos.

Elijas lo 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 manifiesto.

Publicar desde el directorio del plugin

Inicia sesión una vez y luego publica desde el directorio que contiene emdash-plugin.jsonc:

emdash-plugin login alice.example.com
emdash-plugin publish

publish ejecuta las mismas comprobaciones de compilación y validación que bundle, crea el archivo gzip, lo sube a tu servidor personal de datos (PDS), sube las imágenes de la ficha declaradas y escribe el registro de la publicación.

Cuando hay un repositorio HTTPS canónico disponible, el comando lo añade al perfil del paquete con una procedencia opcional. Los perfiles sin metadatos de repositorio también permiten publicaciones sin procedencia. Si profile setup configuró el paquete para exigir procedencia, publica en su lugar mediante el flujo de trabajo de GitHub Actions generado.

Bundle

bundle ejecuta build, valida, recopila los recursos 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 opciones:

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

Opción	Valor predeterminado	Descripción
`--dir`	Directorio actual	Directorio de código fuente del plugin.
`--out-dir`, `-o`	`dist`	Directorio de salida del tarball.
`--validate-only`	`false`	Omite el tarball, pero sigue generando los artefactos de `dist/`.

Contenido del tarball

Archivo	Obligatorio	Descripción
`manifest.json`	Sí	Manifiesto generado: id, versión, capabilities, hosts y los hooks y rutas leídos de tu código fuente. No lo mantienes a mano.
`backend.js`	Sí	El archivo de runtime compilado y autocontenido (`dist/plugin.mjs`).
`README.md`	No	Documentación del plugin.
`icon.png`	No	Icono convencional del bundle. Debe ser un PNG legible; se recomienda 256×256.
`screenshots/`	No	Hasta ocho archivos `.png`, `.jpg` o `.jpeg`; se recomienda 1920×1080 o menos.

Validación

bundle (y --validate-only) comprueban:

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 módulos integrados de Node en backend.js: el código sandbox no puede importar fs, path, child_process, etc. Usa APIs web o mueve esa lógica a un plugin nativo.
Coherencia de las capabilities: los nombres deben pertenecer al conjunto reconocido.
Coherencia del contrato de confianza: las reglas cruzadas de network:request / allowedHosts de Capabilities y hosts.
Recursos convencionales del bundle: un icon.png o una captura que no se pueda leer se omite. La CLI avisa cuando el icono no mide 256×256 o una captura supera 1920×1080, pero las dimensiones por sí solas no hacen fallar el bundle. Cada archivo incluido sigue contando para los límites de número de archivos y de tamaño descomprimido.

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

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

Publish

Publica el código fuente actual y aloja sus artefactos en tu PDS:

emdash-plugin publish

El siguiente bloque del manifiesto añade imágenes de la ficha. Las rutas son relativas a emdash-plugin.jsonc; se admiten PNG, JPEG y WebP.

{
  "release": {
    "artifacts": {
      "icon": { "file": "./icon.png" },
      "banner": { "file": "./banner.webp" },
      "screenshots": [
        { "file": "./images/editor.png" },
        { "file": "./images/settings.jpg", "lang": "en" }
      ]
    }
  }
}

Al publicar, cada imagen declarada se sube al PDS del publisher y su referencia de blob se escribe en el registro de la publicación. Cada imagen está limitada a 1 MiB y a 8.192 píxeles en cualquiera de sus dimensiones; una publicación puede declarar hasta ocho capturas de pantalla. bundle también empaqueta en el tarball el icon.png convencional y los archivos PNG y JPEG de screenshots/, los declare o no el manifiesto, y cada archivo empaquetado cuenta para los límites de tamaño de 128 KB por archivo y 256 KB en total. Guarda las capturas declaradas en otra carpeta, como images/. Consulta Campos de la versión para ver la forma completa.

Lo que hace publish:

Compila el plugin, valida los límites descomprimidos y crea el archivo gzip.
Reanuda la sesión de tu cuenta Atmosphere y comprueba la fijación del publisher.
Confirma que la concesión de OAuth incluye los scopes de blobs de paquete e imagen.
Sube el paquete y las imágenes declaradas a tu PDS y verifica cada CID de blob devuelto frente a los bytes subidos.
Crea el perfil del paquete en la primera publicación y escribe el registro inmutable de la publicación.

La CLI identifica el paquete publicado como @<publisher-handle>/<slug>, imprime la página pública que estará disponible tras la aprobación y ofrece un comando emdash-plugin info … --version <version> --watch. Ese comando lee directamente las comprobaciones actuales del labeler; los metadatos de un paquete sin aprobar siguen ausentes de las respuestas del agregador y del sitio público de plugins.

Si un inicio de sesión existente es anterior a la publicación de blobs, publish informa MISSING_BLOB_SCOPE. Ejecuta emdash-plugin logout y vuelve a iniciar sesión para aprobar los nuevos scopes.

Usar una URL de paquete externa

Pasa --url cuando el bundle del paquete ya esté disponible por HTTPS o cuando el proveedor de la cuenta no acepte blobs gzip:

emdash-plugin publish --url https://downloads.example.com/gallery-1.0.0.tar.gz

La CLI descarga la URL, valida el bundle servido y calcula su suma de comprobación. En esta ruta no sube el blob del paquete. Las imágenes de la ficha siguen usando blobs del PDS.

Para comparar los bytes alojados con un tarball local, añade --local:

emdash-plugin publish \\
  --url https://downloads.example.com/gallery-1.0.0.tar.gz \\
  --local dist/gallery-1.0.0.tar.gz

Las versiones son inmutables por defecto

emdash-plugin publish se niega a reemplazar una publicación existente con el mismo slug y versión. Sube version antes de volver a publicar. La compilación lee version de package.json (consulta Mantenga un único valor de versión). Sube major cuando se amplía el contrato de confianza, minor para nuevos hooks o rutas y patch para correcciones.

Desajuste de publisher

Si publish falla con MANIFEST_PUBLISHER_MISMATCH, la sesión activa es una cuenta Atmosphere distinta del publisher fijado en el manifiesto. Cambia a la cuenta fijada con emdash-plugin switch <did>, o actualiza publisher en el manifiesto si realmente estás transfiriendo el plugin a una cuenta nueva. Consulta Usar una cuenta existente para gestionar las sesiones.

Qué leer a continuación

La CLI emdash-plugin: cada comando
Publicaciones automatizadas de plugins: publica desde un flujo de trabajo aprobado de GitHub Actions
El manifiesto del plugin: campos, contrato de confianza, fijación del publisher
Capabilities y seguridad