Impacchettamento e pubblicazione | EmDash CMS Everything

Una volta che il tuo plugin sandbox funziona, pubblicalo in modo che altri siti possano installarlo. La pubblicazione è solo per sandbox — i plugin nativi si distribuiscono tramite npm.

Quando pubblichi, la CLI registra la release nel tuo account Atmosphere. Tu ospiti il tarball — come asset di release GitHub, R2, S3 o qualsiasi URL pubblica — e il registro memorizza un link ad esso.

Prerequisiti

Un 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 confermare.
Una version (in package.json, o il manifest per plugin registry-only).
Un account Atmosphere per pubblicare.

Il tuo account Atmosphere

Pubblichi sotto un account Atmosphere: un’identità portatile di proprietà dell’utente utilizzata su Bluesky e altre app nella 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 singola app. EmDash utilizza questo account come tua identità di publisher: ogni release che pubblichi è un record nel tuo account, firmato come te.

EmDash utilizza gli stessi account Atmosphere del suo login Atmosphere per i siti.

Usare un account esistente

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

emdash-plugin login alice.bsky.social

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

Registrarsi per un account

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

Un’app, come Bluesky. La registrazione su Bluesky crea un account Atmosphere ospitato da Bluesky. Questo è il percorso più veloce.
Un provider indipendente. Host di account gestiti dalla comunità o orientati alla privacy. Esplora le opzioni su atmosphereaccount.com.
Self-hosted. Esegui il tuo provider per il controllo completo sulla tua identità e dati.

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

Tre passi

I seguenti comandi effettuano il login, costruiscono un tarball e pubblicano una release che punta al tarball ospitato:

emdash-plugin login                     # se non già loggato
emdash-plugin bundle                    # produce dist/<slug>-<version>.tar.gz
# carica quel tarball su un URL pubblico, poi:
emdash-plugin publish --url https://your-host/<slug>-<version>.tar.gz

bundle stampa i prossimi due passi quando finisce, inclusa l’invocazione di --url, così non devi ricordare la forma.

Bundle

bundle esegue build, valida, raccoglie gli assets e crea un tarball. All’interno del tarball, plugin.mjs è impacchettato come backend.js (il nome 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 per il tarball.
`--validate-only`	`false`	Salta il tarball, ma produce comunque gli artefatti di `dist/`.

Contenuto del tarball

File	Richiesto	Descrizione
`manifest.json`	Sì	Manifest generato: id, version, capabilities, hosts e gli hooks e routes letti dalla tua fonte. Non lo mantieni manualmente.
`backend.js`	Sì	Il file runtime costruito e autocontenuto (`dist/plugin.mjs`).
`README.md`	No	Documentazione del plugin.
`icon.png`	No	PNG 256×256.
`screenshots/`	No	Fino a 5, max 1920×1080.

Validazione

bundle (e --validate-only) controllano:

Limiti di dimensione (RFC 0001, decompressi): totale ≤ 256 KB, per file ≤ 128 KB, ≤ 20 file. Il tarball gzippato è una frazione di quello.
Nessun built-in Node in backend.js — il codice sandbox non può importare fs, path, child_process, ecc. Usa le Web API, o sposta quella logica in un plugin nativo.
Sanità delle capabilities — i nomi devono essere nell’insieme riconosciuto.
Coerenza del contratto di fiducia — le regole incrociate di network:request / allowedHosts dal manifest.
Limiti degli assets — icona 256×256, ≤ 5 screenshot a ≤ 1920×1080.

Per ispezionare il tarball prima della pubblicazione, elenca il suo contenuto:

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

Publish

La pubblicazione scrive il record della release. Il tarball deve già essere ospitato su un URL pubblico:

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

--url è obbligatorio: è dove vivono i byte del plugin, e il record del registro punta ad esso. Per verificare che l’URL ospitato serva esattamente i byte che hai costruito prima di scrivere il record, passa --local:

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

Cosa fa publish:

Recupera il tarball a --url (con guardie di URL e dimensione) ed estrae il manifest da quei byte.
Riprende la tua sessione account Atmosphere e controlla il pinning del publisher — la sessione attiva deve corrispondere al publisher fissato del manifest, altrimenti rifiuta con MANIFEST_PUBLISHER_MISMATCH.
Crea il profilo del pacchetto dal manifest alla prima pubblicazione (license, autore, contatto di sicurezza). Nelle pubblicazioni successive, vince il profilo esistente.
Pubblica i record di profilo e release sul tuo account.

Alla prima pubblicazione puoi fornire campi di profilo per flag (--license, --security-email, …) invece del manifest; i flag espliciti sovrascrivono i valori del manifest, il che è utile in CI. --no-manifest rinuncia completamente al manifest.

Le versioni sono immutabili

Una versione pubblicata non può essere sovrascritta o ripubblicata. Incrementa version prima di ripubblicare. Il build legge version da package.json (vedi il riferimento al manifest). Incrementa major per un contratto di fiducia allargato, minor per nuovi hooks o routes, e patch per correzioni.

Mismatch del publisher

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

Cosa leggere dopo

La CLI emdash-plugin — tutti i comandi
Il manifest — campi, contratto di fiducia, pinning del publisher
Capabilities e sicurezza