Empaqueter et publier | EmDash CMS Everything

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

Publiez directement depuis la CLI, ou utilisez le service de releases automatisées pour construire et publier depuis GitHub Actions. Les deux chemins écrivent la release dans votre compte Atmosphere. Vous n’avez besoin d’un hébergeur d’artefacts séparé que lorsque vous choisissez explicitement le chemin CLI direct --url.

Prérequis

Un 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 confirmer.
Une version (dans package.json, ou le manifeste pour les plugins registry-only).
Un compte Atmosphere sous lequel publier.

Choisir une méthode de publication

Les deux méthodes créent des enregistrements de package et de release appartenant à l’éditeur. Choisissez où la build de release doit s’exécuter et quelle credential doit l’autoriser.

Méthode	Utilisez-la quand	Accès au compte
`emdash-plugin publish`	Vous construisez et publiez depuis votre machine ou un autre environnement de confiance.	La session CLI locale écrit le profil du package, la release et les blobs.
Releases automatisées	GitHub Actions doit construire les releases à partir de tags de version ou d’exécutions manuelles du workflow.	La CLI locale amorce le profil ; le service de release conserve l’autorité create-only de release et de blob.

Votre compte Atmosphere

Vous publiez sous un compte Atmosphere : une identité portable appartenant à l’utilisateur, utilisée sur Bluesky et d’autres apps du réseau AT Protocol. Un compte est votre unique connexion sur le réseau, avec le même @handle partout, et votre identité et vos données ne sont liées à aucune app unique. EmDash utilise ce compte comme votre identité d’éditeur : chaque release que vous publiez est un enregistrement sur votre propre compte, signé comme 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 un 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 qui est 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 app, comme Bluesky. S’inscrire sur Bluesky crée un compte Atmosphere hébergé par Bluesky. C’est le chemin le plus rapide.
Un fournisseur indépendant. Des hébergeurs de comptes communautaires ou axés sur la vie privée. Explorez les options sur atmosphereaccount.com.
Self-hosted. 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 manifeste.

Publier depuis le répertoire du plugin

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

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

publish exécute les mêmes contrôles de build et de validation que bundle, crée l’archive gzip, la téléverse sur votre personal data server (PDS), téléverse les images de listing déclarées et écrit l’enregistrement de release.

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

Bundle

bundle exécute build, valide, collecte les assets et crée un tarball. À l’intérieur du tarball, plugin.mjs est empaqueté comme 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	Défaut	Description
`--dir`	Répertoire courant	Répertoire source du plugin.
`--out-dir`, `-o`	`dist`	Répertoire de sortie du tarball.
`--validate-only`	`false`	Ignore le tarball, mais produit toujours les artefacts `dist/`.

Contenu du tarball

Fichier	Requis	Description
`manifest.json`	Oui	Manifeste généré : id, version, capabilities, hosts, et les hooks et routes lus depuis votre code source. Vous ne le maintenez pas à la main.
`backend.js`	Oui	Le fichier de runtime construit et autonome (`dist/plugin.mjs`).
`README.md`	Non	Documentation du plugin.
`icon.png`	Non	Icône conventionnelle du bundle. Doit être un PNG lisible ; 256×256 recommandé.
`screenshots/`	Non	Jusqu’à huit fichiers `.png`, `.jpg` ou `.jpeg` ; 1920×1080 ou moins recommandé.

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 gzip 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 des APIs web, ou déplacez cette logique dans un plugin natif.
Sanité 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 hosts.
Assets conventionnels du bundle — une icon.png ou capture illisible est ignorée. La CLI avertit lorsque l’icône n’est pas 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 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 le code source actuel et hébergez ses artefacts sur votre PDS :

emdash-plugin publish

Le bloc manifeste suivant ajoute des images de listing. 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": "./screenshots/editor.png" },
        { "file": "./screenshots/settings.jpg", "lang": "en" }
      ]
    }
  }
}

Les images de listing déclarées dans le manifeste sont distinctes des fichiers conventionnels icon.png et screenshots/ inclus dans le tarball. La publication téléverse chaque image déclarée vers le PDS de l’éditeur et écrit sa référence de blob dans l’enregistrement de release. Chaque image est limitée à 1 MiB et 8 192 pixels dans chaque dimension ; une release peut déclarer jusqu’à huit captures. Voir Champs de release pour la forme complète.

Ce que fait publish :

Construit le plugin, valide les limites décompressées et crée l’archive gzip.
Reprend votre session de compte Atmosphere et vérifie le pinning de l’éditeur.
Confirme que l’octroi OAuth inclut les scopes de blob de package et d’image.
Téléverse le package et les images déclarées vers votre PDS, et vérifie chaque CID de blob renvoyé contre les octets téléversés.
Crée le profil du package à la première publication et écrit l’enregistrement de release immuable.

La CLI identifie le package publié comme @<publisher-handle>/<slug>, imprime la page publique qui devient disponible après approbation, et donne une commande emdash-plugin info … --version <version> --watch. Cette commande lit les contrôles actuels du labeler directement ; les métadonnées des packages non approuvés restent absentes des réponses de l’agrégateur et du site public des plugins.

Si une connexion existante précède la publication des blobs, publish signale MISSING_BLOB_SCOPE. Exécutez emdash-plugin logout et reconnectez-vous pour approuver les nouveaux scopes.

Utiliser une URL de package externe

Passez --url lorsque le bundle du package est déjà disponible via HTTPS ou que le fournisseur de 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 checksum. Elle ne téléverse pas le blob du package sur ce chemin. Les images de listing utilisent toujours des blobs 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 release existante avec le même slug et la même version. Incrémentez version avant de republier. La build lit version depuis 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 les correctifs.

Incompatibilité d’éditeur

Si publish échoue avec MANIFEST_PUBLISHER_MISMATCH, la session active est un compte Atmosphere différent du 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. Voir Utiliser un compte existant pour gérer les sessions.

Suite de lecture

La CLI emdash-plugin — chaque commande
Releases automatisées de plugins — publier depuis un workflow GitHub Actions approuvé
Le manifeste — champs, contrat de confiance, pinning de l’éditeur
Capabilities et sécurité