Empaqueter et publier

Publiez un plugin sandboxed fonctionnel pour que d’autres sites puissent l’installer. La publication ne concerne que les plugins sandboxed — les plugins natifs se distribuent via npm.

Publiez directement depuis la CLI, ou utilisez le service de publications automatisées pour construire et publier depuis GitHub Actions. Les deux voies écrivent la publication dans votre compte Atmosphere. Vous n’avez besoin d’un hébergeur d’artefacts distinct que si vous choisissez explicitement la voie --url de la CLI directe.

Prérequis

• Un fichier emdash-plugin.jsonc valide avec slug, publisher, license, un auteur (author ou authors) et un contact sécurité (security ou securityContacts). Exécutez emdash-plugin validate pour le confirmer.
• Une version (dans package.json, ou dans le manifeste pour les plugins uniquement présents dans le registre).
• Un compte Atmosphere sous lequel publier.

Choisir une méthode de publication

Les deux méthodes créent des enregistrements de paquet et de publication appartenant au publisher. Choisissez où doit s’exécuter la construction de la publication et quel identifiant doit l’autoriser.

Votre compte Atmosphere

Vous publiez sous un compte Atmosphere : une identité portable, détenue par l’utilisateur, utilisée dans Bluesky et d’autres applications du réseau AT Protocol. Un compte est votre unique connexion sur tout le réseau, avec le même @handle partout, et votre identité et vos données ne sont liées à aucune application en particulier. EmDash utilise ce compte comme votre identité de publisher : chaque publication que vous faites est un enregistrement dans votre propre compte, signé en votre nom.

EmDash utilise les mêmes comptes Atmosphere pour la connexion Atmosphere des sites.

Utiliser un compte existant

Si vous avez déjà un compte Bluesky ou un autre compte Atmosphere, connectez-vous avec son handle :

emdash-plugin login alice.bsky.social

Cela ouvre dans le navigateur la page de connexion du fournisseur de votre compte. EmDash ne voit jamais votre mot de passe. emdash-plugin whoami liste vos sessions enregistrées ; emdash-plugin switch <did> change la session active.

Créer un compte

Si vous n’avez pas encore de compte Atmosphere, créez-en un chez n’importe quel fournisseur, puis exécutez emdash-plugin login <your-handle>. Vos options :

• Une application, comme Bluesky. S’inscrire sur Bluesky crée un compte Atmosphere hébergé par Bluesky. C’est la voie la plus rapide.
• Un fournisseur indépendant. Des hébergeurs de comptes gérés par la communauté ou axés sur la confidentialité. Parcourez les options sur atmosphereaccount.com.
• Auto-hébergé. Exploitez votre propre fournisseur pour garder un contrôle total sur votre identité et vos données.

Quel que soit votre choix, le @handle de ce compte est ce que vous passez à emdash-plugin login, et le DID du compte est ce que vous épinglez comme publisher dans votre manifeste.

Publier depuis le répertoire du plugin

Connectez-vous une fois, puis publiez depuis le répertoire contenant emdash-plugin.jsonc :

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

publish exécute les mêmes vérifications de construction et de validation que bundle, crée l’archive gzip, la téléverse sur votre serveur de données personnel (PDS), téléverse les images de fiche déclarées et écrit l’enregistrement de publication.

Lorsqu’un dépôt HTTPS canonique est disponible, la commande l’ajoute au profil du paquet avec une provenance facultative. Les profils sans métadonnées de dépôt autorisent aussi les publications sans provenance. Si profile setup a configuré le paquet pour exiger une provenance, publiez plutôt via le workflow GitHub Actions généré.

Bundle

bundle exécute build, valide, collecte les ressources et crée un tarball. À l’intérieur du tarball, plugin.mjs est empaqueté sous le nom backend.js (le nom de fichier attendu par le registre).

La commande accepte les options suivantes :

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

Contenu du tarball

Validation

bundle (et --validate-only) vérifient :

• Limites de taille (RFC 0001, décompressé) : total ≤ 256 Ko, par fichier ≤ 128 Ko, ≤ 20 fichiers. Le tarball compressé en gzip n’en représente qu’une fraction.
• Aucun module intégré de Node dans backend.js — le code sandbox ne peut pas importer fs, path, child_process, etc. Utilisez les API Web, ou déplacez cette logique vers un plugin natif.
• Cohérence des capabilities — les noms doivent appartenir à l’ensemble reconnu.
• Cohérence du contrat de confiance — les règles croisées network:request / allowedHosts de Capabilities et hôtes.
• Ressources de bundle conventionnelles — une icon.png ou une capture illisible est ignorée. La CLI avertit lorsque l’icône n’est pas en 256×256 ou qu’une capture dépasse 1920×1080, mais les dimensions seules ne font pas échouer le bundle. Chaque fichier inclus compte toujours dans les limites de nombre de fichiers et de taille décompressée.

Pour inspecter le tarball avant de publier, listez son contenu :

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

Publish

Publiez la source actuelle et hébergez ses artefacts sur votre PDS :

emdash-plugin publish

Le bloc de manifeste suivant ajoute des images de fiche. Les chemins sont relatifs à emdash-plugin.jsonc ; PNG, JPEG et WebP sont pris en charge.

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

Lors de la publication, chaque image déclarée est téléversée sur le PDS du publisher et sa référence de blob est écrite dans l’enregistrement de publication. Chaque image est limitée à 1 Mio et à 8 192 pixels dans chaque dimension ; une publication peut déclarer jusqu’à huit captures d’écran. bundle empaquette aussi dans le tarball l’icon.png conventionnelle ainsi que les fichiers PNG et JPEG de screenshots/, que le manifeste les déclare ou non, et chaque fichier empaqueté compte dans les limites de taille de 128 Ko par fichier et 256 Ko au total. Stockez les captures déclarées dans un autre dossier, tel que images/. Consultez Champs de release pour la forme complète.

Ce que fait publish :

La CLI identifie le paquet publié sous la forme @<publisher-handle>/<slug>, affiche la page publique qui devient disponible après approbation et fournit une commande emdash-plugin info … --version <version> --watch. Cette commande lit directement les vérifications en cours du labeler ; les métadonnées d’un paquet non approuvé restent absentes des réponses de l’agrégateur et du site public des plugins.

Si une connexion existante est antérieure à la publication de blobs, publish signale MISSING_BLOB_SCOPE. Exécutez emdash-plugin logout, puis reconnectez-vous pour approuver les nouveaux scopes.

Utiliser une URL de package externe

Passez --url lorsque le bundle du paquet est déjà disponible via HTTPS ou que le fournisseur du compte n’accepte pas les blobs gzip :

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

La CLI télécharge l’URL, valide le bundle servi et calcule sa somme de contrôle. Elle ne téléverse pas le blob du paquet sur cette voie. Les images de fiche utilisent toujours des blobs du PDS.

Pour comparer les octets hébergés à un tarball local, ajoutez --local :

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

Les versions sont immuables par défaut

emdash-plugin publish refuse de remplacer une publication existante ayant le même slug et la même version. Incrémentez version avant de publier de nouveau. La construction lit version dans package.json (voir Conserver une seule valeur de version). Incrémentez major pour un contrat de confiance élargi, minor pour de nouveaux hooks ou routes, et patch pour des correctifs.

Incompatibilité de publisher

Si publish échoue avec MANIFEST_PUBLISHER_MISMATCH, la session active correspond à un autre compte Atmosphere que le publisher épinglé dans le manifeste. Passez au compte épinglé avec emdash-plugin switch <did>, ou mettez à jour publisher dans le manifeste si vous transférez réellement le plugin vers un nouveau compte. Consultez Utiliser un compte existant pour gérer les sessions.

Suite de lecture

• La CLI emdash-plugin — chaque commande
• Publications automatisées de plugins — publier depuis un workflow GitHub Actions approuvé
• Le manifeste du plugin — champs, contrat de confiance, épinglage du publisher
• Capabilities et sécurité