Empaquetar y publicar

Publica un plugin sandboxed funcional para que otros sitios puedan instalarlo. Publicar es solo sandboxed: los plugins nativos se distribuyen por npm.

Publica directamente desde la CLI, o usa el servicio de releases automatizadas para construir y publicar desde GitHub Actions. Ambos caminos escriben el release en tu cuenta Atmosphere. Solo necesitas un host de artefactos separado 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 confirmar.
• Un version (en package.json, o el manifiesto para plugins solo de registro).
• Una cuenta Atmosphere bajo la que publicar.

Elegir un método de publicación

Ambos métodos crean registros de paquete y release propiedad del publisher. Elige dónde debe ejecutarse la build del release y qué credencial debe autorizarla.

Tu cuenta Atmosphere

Publicas bajo una cuenta Atmosphere: una identidad portable y propiedad del usuario usada en Bluesky y otras apps de la red AT Protocol. Una cuenta es tu único inicio de sesión en la red, con el mismo @handle en todas partes, y tu identidad y datos no están ligados a una sola app. EmDash usa esta cuenta como tu identidad de publisher: cada release que publicas es un registro en tu propia cuenta, firmado como tú.

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

Usar una cuenta existente

Si ya tienes una cuenta de Bluesky u otra cuenta 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 cuenta 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 Atmosphere, crea una a través de cualquier proveedor y luego ejecuta emdash-plugin login <your-handle>. Tus opciones:

• Una app, como Bluesky. Registrarse en Bluesky crea una cuenta Atmosphere alojada por Bluesky. Es la ruta más rápida.
• Un proveedor independiente. Hosts de cuentas comunitarios o centrados en la privacidad. Explora opciones en atmosphereaccount.com.
• Self-hosted. Ejecuta tu propio proveedor para 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 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 build y validación que bundle, crea el archivo gzip, lo sube a tu personal data server (PDS), sube cualquier imagen de listado declarada y escribe el registro de release.

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

Bundle

bundle ejecuta build, valida, recoge 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 los siguientes flags:

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

Contenido del tarball

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 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 APIs web, o mueve esa lógica a un plugin nativo.
• Sanidad de capabilities — los nombres deben estar en el conjunto reconocido.
• Coherencia del contrato de confianza — las reglas cruzadas network:request / allowedHosts de Capabilities y hosts.
• Assets convencionales del bundle — un icon.png o captura ilegible se omite. La CLI avisa cuando el icono no es 256×256 o una captura supera 1920×1080, pero las dimensiones solas no hacen fallar el bundle. Cada archivo incluido sigue contando hacia los límites de archivos y 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 listado. 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": "./screenshots/editor.png" },
        { "file": "./screenshots/settings.jpg", "lang": "en" }
      ]
    }
  }
}

Las imágenes de listado declaradas en el manifiesto son distintas de los archivos convencionales icon.png y screenshots/ incluidos en el tarball. Publicar sube cada imagen declarada al PDS del publisher y escribe su referencia de blob en el registro de release. Cada imagen está limitada a 1 MiB y 8.192 píxeles en cualquier dimensión; un release puede declarar hasta ocho capturas. Consulta Campos de release para la forma completa.

Qué hace publish:

La CLI identifica el paquete publicado como @<publisher-handle>/<slug>, imprime la página pública que queda disponible tras la aprobación y da un comando emdash-plugin info … --version <version> --watch. Ese comando lee las comprobaciones actuales del labeler directamente; los metadatos de paquetes no aprobados 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 el proveedor de la cuenta no acepta 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 checksum. No sube el blob del paquete en esta ruta. Las imágenes de listado 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 un release existente con el mismo slug y versión. Incrementa version antes de publicar de nuevo. La build lee version de package.json (consulta Mantener un solo valor de versión). Incrementa major para un contrato de confianza ampliado, 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 sesiones.

Qué leer a continuación

• La CLI emdash-plugin — cada comando
• Releases automatizadas de plugins — publicar desde un workflow aprobado de GitHub Actions
• El manifiesto — campos, contrato de confianza, pinning del publisher
• Capabilities y seguridad