Bundle e pubblicazione

Pubblica un plugin sandboxed funzionante così 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 artefact separato solo quando scegli esplicitamente il percorso CLI diretto --url.

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 nel manifesto per i plugin solo-registro).
• Un account Atmosphere con cui pubblicare.

Scegliere un metodo di pubblicazione

Entrambi i metodi creano record di package e release di proprietà dell’editore. Scegli dove deve eseguire la build della release e quale credenziale deve autorizzarla.

Il tuo account Atmosphere

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

EmDash usa gli stessi account Atmosphere del suo accesso Atmosphere per i 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 la pagina di accesso del tuo provider di account nel browser. EmDash non vede mai la tua password. emdash-plugin whoami elenca le 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 e poi esegui emdash-plugin login <your-handle>. Le tue opzioni:

• Un’app, come Bluesky. Registrarsi su Bluesky crea un account Atmosphere ospitato da Bluesky. È il percorso più veloce.
• Un provider indipendente. Host di account comunitari o incentrati sulla privacy. Esplora le opzioni su atmosphereaccount.com.
• Self-hosted. Esegui il tuo provider per il controllo totale su identità e dati.

Qualunque sia la scelta, l’@handle di quell’account è ciò che passi a emdash-plugin login, e il DID dell’account è ciò che fissi come publisher nel 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 validazione di bundle, crea l’archivio gzip, lo carica sul tuo personal data server (PDS), carica le immagini di listing dichiarate e scrive il record di release.

Quando è disponibile un repository HTTPS canonico, il comando lo aggiunge al profilo del package con provenance opzionale. Anche i profili senza metadati del repository consentono release senza provenance. Se profile setup ha configurato il package per richiedere la provenance, pubblica tramite il workflow GitHub Actions generato.

Bundle

bundle esegue build, valida, raccoglie gli asset e crea un tarball. All’interno del tarball, plugin.mjs viene 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]

Contenuto del tarball

Validazione

bundle (e --validate-only) controllano:

• Limiti di dimensione (RFC 0001, decompresso): totale ≤ 256 KB, per file ≤ 128 KB, ≤ 20 file. Il tarball gzip è una frazione di questo.
• Nessun built-in Node in backend.js — il codice sandbox non può importare fs, path, child_process, ecc. Usa API web, oppure sposta quella logica in un plugin nativo.
• Sanità delle capabilities — i nomi devono appartenere all’insieme riconosciuto.
• Coerenza del contratto di fiducia — le regole crociate network:request / allowedHosts da Capabilities 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 di file e dimensione decompressa.

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

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

Publish

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

emdash-plugin publish

Il blocco manifesto seguente aggiunge immagini di listing. 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": "./screenshots/editor.png" },
        { "file": "./screenshots/settings.jpg", "lang": "en" }
      ]
    }
  }
}

Le immagini di listing dichiarate nel manifesto sono distinte dai file convenzionali icon.png e screenshots/ inclusi nel tarball. La pubblicazione carica ogni immagine dichiarata sul PDS del publisher e scrive il suo riferimento blob nel record di release. Ogni immagine è limitata a 1 MiB e 8.192 pixel in ciascuna dimensione; una release può dichiarare fino a otto screenshot. Vedi Campi di release per la forma completa.

Cosa fa publish:

La CLI identifica il package 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 attuali del labeler; i metadati dei package non approvati restano assenti dalle risposte dell’aggregatore e dal sito pubblico dei plugin.

Se un accesso esistente precede la pubblicazione dei blob, publish segnala MISSING_BLOB_SCOPE. Esegui emdash-plugin logout e accedi di nuovo per approvare i nuovi scope.

Usare un URL di package esterno

Passa --url quando il bundle del package è già disponibile via HTTPS o 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, valida il bundle servito e calcola il suo checksum. Non carica il blob del package su questo percorso. Le immagini di listing usano comunque blob 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 versione. Incrementa version prima di ripubblicare. 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.

Disallineamento 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 — pubblicare da un workflow GitHub Actions approvato
• Il manifesto — campi, contratto di fiducia, pinning del publisher
• Capabilities e sicurezza