Empaquetage et publication | EmDash CMS Everything

Une fois que votre plugin sandbox fonctionne, publiez-le afin que d’autres sites puissent l’installer. La publication est réservée aux sandbox uniquement — les plugins natifs se distribuent via npm.

Lorsque vous publiez, la CLI enregistre la version dans votre propre compte Atmosphere. Vous hébergez le tarball vous-même — un asset de release GitHub, R2, S3 ou toute URL publique — et le registre stocke un lien vers celui-ci.

Prérequis

Un emdash-plugin.jsonc valide avec slug, publisher, license, un auteur (author ou authors) et un contact de sécurité (security ou securityContacts). Exécutez emdash-plugin validate pour confirmer.
Une version (dans package.json, ou le manifest pour les plugins registry-only).
Un compte Atmosphere pour publier.

Votre compte Atmosphere

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

EmDash utilise les mêmes comptes Atmosphere que sa connexion Atmosphere pour les sites.

Utiliser un compte existant

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

emdash-plugin login alice.bsky.social

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

S’inscrire pour un compte

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

Une application, comme Bluesky. S’inscrire à 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 communautaires ou axés sur la confidentialité. Parcourez les options sur atmosphereaccount.com.
Auto-hébergé. Exécutez votre propre fournisseur pour 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 manifest.

Trois étapes

Les commandes suivantes se connectent, construisent un tarball et publient une version qui pointe vers le tarball hébergé :

emdash-plugin login                     # si pas déjà connecté
emdash-plugin bundle                    # produit dist/<slug>-<version>.tar.gz
# téléchargez ce tarball vers une URL publique, puis :
emdash-plugin publish --url https://your-host/<slug>-<version>.tar.gz

bundle affiche les deux prochaines étapes lorsqu’il se termine, y compris l’invocation de --url, vous n’avez donc pas à mémoriser la forme.

Bundle

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

La commande accepte les flags suivants :

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

Flag	Par défaut	Description
`--dir`	Répertoire actuel	Répertoire source du plugin.
`--out-dir`, `-o`	`dist`	Répertoire de sortie pour le tarball.
`--validate-only`	`false`	Ignorer le tarball, mais produire quand même les artefacts de `dist/`.

Contenu du tarball

Fichier	Requis	Description
`manifest.json`	Oui	Manifest généré : id, version, capabilities, hosts et les hooks et routes lus depuis votre source. Vous ne le maintenez pas manuellement.
`backend.js`	Oui	Le fichier de runtime construit et autonome (`dist/plugin.mjs`).
`README.md`	Non	Documentation du plugin.
`icon.png`	Non	PNG de 256×256.
`screenshots/`	Non	Jusqu’à 5, max 1920×1080.

Validation

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

Limites de taille (RFC 0001, décompressé) : total ≤ 256 KB, par fichier ≤ 128 KB, ≤ 20 fichiers. Le tarball gzippé est une fraction de cela.
Pas de built-ins Node dans backend.js — le code sandbox ne peut pas importer fs, path, child_process, etc. Utilisez les Web APIs, ou déplacez cette logique vers un plugin natif.
Sanité des capabilities — les noms doivent être dans l’ensemble reconnu.
Cohérence du contrat de confiance — les règles croisées de network:request / allowedHosts du manifest.
Limites des assets — icône 256×256, ≤ 5 captures d’écran à ≤ 1920×1080.

Pour inspecter le tarball avant publication, listez son contenu :

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

Publish

La publication écrit l’enregistrement de version. Le tarball doit déjà être hébergé à une URL publique :

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

--url est obligatoire : c’est là que vivent les octets du plugin, et l’enregistrement du registre y pointe. Pour vérifier que l’URL hébergée sert exactement les octets que vous avez construits avant d’écrire l’enregistrement, passez --local :

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

Ce que fait publish :

Récupère le tarball à --url (avec des gardes d’URL et de taille) et extrait le manifest de ces octets.
Reprend votre session de compte Atmosphere et vérifie l’épinglage du publisher — la session active doit correspondre au publisher épinglé du manifest, sinon elle refuse avec MANIFEST_PUBLISHER_MISMATCH.
Crée le profil du package à partir du manifest lors de la première publication (license, auteur, contact de sécurité). Lors des publications ultérieures, le profil existant l’emporte.
Publie les enregistrements de profil et de version sur votre compte.

Lors de la première publication, vous pouvez fournir des champs de profil par flag (--license, --security-email, …) au lieu du manifest ; les flags explicites remplacent les valeurs du manifest, ce qui est pratique en CI. --no-manifest renonce entièrement au manifest.

Les versions sont immuables

Une version publiée ne peut pas être écrasée ou republiée. Augmentez version avant de republier. Le build lit version de package.json (voir la référence du manifest). Augmentez major pour un contrat de confiance élargi, minor pour de nouveaux hooks ou routes, et patch pour des corrections.

Désaccord de publisher

Si publish échoue avec MANIFEST_PUBLISHER_MISMATCH, la session active est un compte Atmosphere différent du publisher épinglé du manifest. Basculez vers le compte épinglé avec emdash-plugin switch <did>, ou mettez à jour publisher dans le manifest si vous transférez réellement le plugin vers un nouveau compte. Voir Utiliser un compte existant pour gérer les sessions.

Que lire ensuite

La CLI emdash-plugin — toutes les commandes
Le manifest — champs, contrat de confiance, épinglage du publisher
Capabilities et sécurité