Creare il bundle e pubblicare | EmDash CMS Everything

Pubblica un plugin sandboxed funzionante in modo che altri siti possano installarlo. La pubblicazione riguarda solo i plugin sandboxed: i plugin nativi si distribuiscono tramite npm.

Pubblica direttamente dalla CLI, oppure usa il servizio di release automatiche per costruire e pubblicare da GitHub Actions. Entrambi i percorsi scrivono la release sul tuo account Atmosphere. Ti serve un host di artefatti separato solo quando scegli esplicitamente il percorso --url della CLI diretta.

Prerequisiti

Un file emdash-plugin.jsonc valido con slug, publisher, license, un autore (author o authors) e un contatto di sicurezza (security o securityContacts). Esegui emdash-plugin validate per confermarlo.
Una version (in package.json, oppure nel manifesto per i plugin presenti solo nel registro).
Un account Atmosphere con cui pubblicare.

Scegliere un metodo di pubblicazione

Entrambi i metodi creano record di pacchetto e di release di proprietà del publisher. Scegli dove deve essere eseguita la build della release e quale credenziale deve autorizzarla.

Metodo	Usalo quando	Accesso all’account
`emdash-plugin publish`	Costruisci e pubblichi dal tuo computer o da un altro ambiente fidato.	La sessione locale della CLI scrive il profilo del pacchetto, la release e i blob.
Release automatiche	GitHub Actions deve costruire le release da tag di versione o da esecuzioni manuali del workflow.	La CLI locale prepara il profilo; il servizio di release mantiene solo l’autorità di creare release e blob.

Il tuo account Atmosphere

Pubblichi con un account Atmosphere: un’identità portabile, di proprietà dell’utente, usata in Bluesky e in altre app della rete AT Protocol. Un account è il tuo unico login su tutta la rete, con lo stesso @handle ovunque, e la tua identità e i tuoi dati non sono legati a nessuna app in particolare. EmDash usa questo account come tua identità di publisher: ogni release che pubblichi è un record nel tuo account, firmato a tuo nome.

EmDash usa gli stessi account Atmosphere anche per l’accesso Atmosphere dei siti.

Usare un account esistente

Se hai già un account Bluesky o un altro account Atmosphere, accedi con il suo handle:

emdash-plugin login alice.bsky.social

Questo apre nel browser la pagina di accesso del provider del tuo account. EmDash non vede mai la tua password. emdash-plugin whoami elenca le tue sessioni memorizzate; emdash-plugin switch <did> cambia quella attiva.

Registrare un account

Se non hai ancora un account Atmosphere, creane uno con un provider qualsiasi, quindi esegui emdash-plugin login <your-handle>. Le tue opzioni:

Un’app, come Bluesky. Registrarsi a Bluesky crea un account Atmosphere ospitato da Bluesky. È la strada più rapida.
Un provider indipendente. Host di account gestiti dalla community o orientati alla privacy. Sfoglia le opzioni su atmosphereaccount.com.
Self-hosted. Gestisci il tuo provider per avere il pieno controllo sulla tua identità e sui tuoi dati.

Qualunque scelta tu faccia, l’@handle di quell’account è ciò che passi a emdash-plugin login, e il DID dell’account è ciò che fissi come publisher nel tuo manifesto.

Pubblicare dalla directory del plugin

Accedi una volta, poi pubblica dalla directory che contiene emdash-plugin.jsonc:

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

publish esegue gli stessi controlli di build e di convalida di bundle, crea l’archivio gzip, lo carica sul tuo server dati personale (PDS), carica le eventuali immagini della scheda dichiarate e scrive il record della release.

Quando è disponibile un repository HTTPS canonico, il comando lo aggiunge al profilo del pacchetto con una provenienza facoltativa. I profili senza metadati del repository consentono anche release senza provenienza. Se profile setup ha configurato il pacchetto in modo da richiedere la provenienza, pubblica invece tramite il workflow GitHub Actions generato.

Bundle

bundle esegue build, convalida, raccoglie gli asset e crea un tarball. All’interno del tarball, plugin.mjs viene impacchettato come backend.js (il nome di file che il registro si aspetta).

Il comando accetta i seguenti flag:

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

Flag	Predefinito	Descrizione
`--dir`	Directory corrente	Directory sorgente del plugin.
`--out-dir`, `-o`	`dist`	Directory di output del tarball.
`--validate-only`	`false`	Salta il tarball, ma produce comunque gli artefatti in `dist/`.

Contenuto del tarball

File	Obbligatorio	Descrizione
`manifest.json`	Sì	Manifesto generato: id, versione, capability, host e gli hook e le route letti dal tuo sorgente. Non lo mantieni a mano.
`backend.js`	Sì	Il file runtime compilato e autonomo (`dist/plugin.mjs`).
`README.md`	No	Documentazione del plugin.
`icon.png`	No	Icona convenzionale del bundle. Deve essere un PNG leggibile; si consiglia 256×256.
`screenshots/`	No	Fino a otto file `.png`, `.jpg` o `.jpeg`; si consiglia 1920×1080 o inferiore.

Validazione

bundle (e --validate-only) controllano:

Limiti di dimensione (RFC 0001, decompresso): totale ≤ 256 KB, per file ≤ 128 KB, ≤ 20 file. Il tarball compresso con gzip ne è una frazione.
Nessun modulo integrato di Node in backend.js: il codice sandbox non può importare fs, path, child_process e così via. Usa le API Web, oppure sposta quella logica in un plugin nativo.
Coerenza delle capability: i nomi devono appartenere all’insieme riconosciuto.
Coerenza del contratto di fiducia: le regole incrociate network:request / allowedHosts descritte in Capability e host.
Asset convenzionali del bundle: un icon.png o uno screenshot illeggibile viene saltato. La CLI avvisa quando l’icona non è 256×256 o uno screenshot supera 1920×1080, ma le sole dimensioni non fanno fallire il bundle. Ogni file incluso conta comunque nei limiti sul numero di file e sulla dimensione decompressa.

Per ispezionare il tarball prima di pubblicare, elenca il suo contenuto:

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

Publish

Pubblica il sorgente corrente e ospita i suoi artefatti sul tuo PDS:

emdash-plugin publish

Il seguente blocco del manifesto aggiunge immagini della scheda. I percorsi sono relativi a emdash-plugin.jsonc; sono supportati PNG, JPEG e WebP.

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

Durante la pubblicazione, ogni immagine dichiarata viene caricata sul PDS del publisher e il suo riferimento al blob viene scritto nel record della release. Ogni immagine è limitata a 1 MiB e a 8.192 pixel in ciascuna dimensione; una release può dichiarare fino a otto screenshot. bundle impacchetta nel tarball anche l’icon.png convenzionale e i file PNG e JPEG in screenshots/, che il manifesto li dichiari o meno, e ogni file impacchettato conta nei limiti di dimensione di 128 KB per file e 256 KB in totale. Conserva gli screenshot dichiarati in un’altra cartella, come images/. Vedi Campi della release per la forma completa.

Cosa fa publish:

Costruisce il plugin, convalida i limiti da decompresso e crea l’archivio gzip.
Riprende la sessione del tuo account Atmosphere e controlla il pinning del publisher.
Conferma che la concessione OAuth includa gli scope dei blob di pacchetto e di immagine.
Carica il pacchetto e le immagini dichiarate sul tuo PDS, poi verifica ogni CID di blob restituito rispetto ai byte caricati.
Crea il profilo del pacchetto alla prima pubblicazione e scrive il record immutabile della release.

La CLI identifica il pacchetto pubblicato come @<publisher-handle>/<slug>, stampa la pagina pubblica che diventa disponibile dopo l’approvazione e fornisce un comando emdash-plugin info … --version <version> --watch. Quel comando legge direttamente i controlli correnti del labeler; i metadati di un pacchetto non approvato restano assenti dalle risposte dell’aggregatore e dal sito pubblico dei plugin.

Se un accesso esistente è precedente alla pubblicazione dei blob, publish segnala MISSING_BLOB_SCOPE. Esegui emdash-plugin logout, poi accedi di nuovo per approvare i nuovi scope.

Usare un URL di pacchetto esterno

Passa --url quando il bundle del pacchetto è già disponibile via HTTPS oppure il provider dell’account non accetta blob gzip:

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

La CLI scarica l’URL, convalida il bundle servito e ne calcola il checksum. Su questo percorso non carica il blob del pacchetto. Le immagini della scheda continuano a usare blob del PDS.

Per confrontare i byte ospitati con un tarball locale, aggiungi --local:

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

Le versioni sono immutabili per impostazione predefinita

emdash-plugin publish rifiuta di sostituire una release esistente con lo stesso slug e la stessa versione. Incrementa version prima di pubblicare di nuovo. La build legge version da package.json (vedi Mantieni un solo valore di versione). Incrementa major per un contratto di fiducia ampliato, minor per nuovi hook o route e patch per le correzioni.

Mancata corrispondenza del publisher

Se publish fallisce con MANIFEST_PUBLISHER_MISMATCH, la sessione attiva è un account Atmosphere diverso dal publisher fissato nel manifesto. Passa all’account fissato con emdash-plugin switch <did>, oppure aggiorna publisher nel manifesto se stai davvero trasferendo il plugin a un nuovo account. Vedi Usare un account esistente per gestire le sessioni.

Cosa leggere dopo

La CLI emdash-plugin: ogni comando
Release automatiche dei plugin: pubblica da un workflow GitHub Actions approvato
Il manifesto del plugin: campi, contratto di fiducia, pinning del publisher
Capability e sicurezza