Bündeln und Veröffentlichen | EmDash CMS Everything

Veröffentlichen Sie ein funktionierendes sandboxed Plugin, damit andere Websites es installieren können. Das Veröffentlichen gilt nur für sandboxed Plugins — native Plugins werden über npm verteilt.

Veröffentlichen Sie direkt über die CLI oder nutzen Sie den automatisierten Release-Dienst, um aus GitHub Actions heraus zu bauen und zu veröffentlichen. Beide Wege schreiben das Release in Ihr Atmosphere-Konto. Einen separaten Artefakt-Host benötigen Sie nur, wenn Sie ausdrücklich den --url-Weg der direkten CLI wählen.

Voraussetzungen

Eine gültige emdash-plugin.jsonc mit slug, publisher, license, einem Autor (author oder authors) und einem Sicherheitskontakt (security oder securityContacts). Führen Sie emdash-plugin validate aus, um das zu bestätigen.
Eine version (in package.json oder, bei reinen Registry-Plugins, im Manifest).
Ein Atmosphere-Konto, unter dem Sie veröffentlichen.

Eine Veröffentlichungsmethode wählen

Beide Methoden erzeugen Paket- und Release-Records, die dem Publisher gehören. Wählen Sie, wo der Release-Build laufen soll und welche Zugangsdaten ihn autorisieren.

Methode	Verwenden, wenn	Kontozugriff
`emdash-plugin publish`	Sie auf Ihrem Computer oder in einer anderen vertrauenswürdigen Umgebung bauen und veröffentlichen.	Die lokale CLI-Sitzung schreibt das Paketprofil, das Release und die Blobs.
Automatisierte Releases	GitHub Actions soll Releases aus Versions-Tags oder manuellen Workflow-Läufen bauen.	Die lokale CLI bereitet das Profil vor; der Release-Dienst behält die reine Berechtigung zum Anlegen von Releases und Blobs.

Ihr Atmosphere-Konto

Sie veröffentlichen unter einem Atmosphere-Konto: einer portablen, nutzereigenen Identität, die in Bluesky und weiteren Apps im AT-Protocol-Netzwerk verwendet wird. Ein Konto ist Ihr einziger Login im gesamten Netzwerk, überall mit demselben @handle, und Ihre Identität und Ihre Daten sind nicht an eine einzelne App gebunden. EmDash nutzt dieses Konto als Ihre Publisher-Identität: Jedes Release, das Sie veröffentlichen, ist ein Record in Ihrem eigenen Konto und wird als Sie signiert.

EmDash verwendet dieselben Atmosphere-Konten auch für die Atmosphere-Anmeldung von Websites.

Ein bestehendes Konto nutzen

Wenn Sie bereits ein Bluesky-Konto oder ein anderes Atmosphere-Konto haben, melden Sie sich mit dessen Handle an:

emdash-plugin login alice.bsky.social

Dadurch öffnet sich im Browser die Anmeldeseite Ihres Konto-Providers. EmDash sieht Ihr Passwort nie. emdash-plugin whoami listet Ihre gespeicherten Sitzungen auf; emdash-plugin switch <did> wechselt die aktive.

Ein Konto erstellen

Wenn Sie noch kein Atmosphere-Konto haben, erstellen Sie eines bei einem beliebigen Provider und führen Sie dann emdash-plugin login <your-handle> aus. Ihre Möglichkeiten:

Eine App, etwa Bluesky. Die Registrierung bei Bluesky erzeugt ein von Bluesky gehostetes Atmosphere-Konto. Das ist der schnellste Weg.
Ein unabhängiger Provider. Von der Community betriebene oder datenschutzorientierte Konto-Hosts. Eine Auswahl finden Sie unter atmosphereaccount.com.
Selbst gehostet. Betreiben Sie Ihren eigenen Provider und behalten Sie die volle Kontrolle über Ihre Identität und Ihre Daten.

Welche Variante Sie auch wählen: Das @handle dieses Kontos übergeben Sie an emdash-plugin login, und die DID des Kontos pinnen Sie als publisher in Ihrem Manifest.

Aus Ihrem Plugin-Verzeichnis veröffentlichen

Melden Sie sich einmal an und veröffentlichen Sie dann aus dem Verzeichnis, das emdash-plugin.jsonc enthält:

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

publish führt dieselben Build- und Validierungsprüfungen aus wie bundle, erstellt das gzip-Archiv, lädt es auf Ihren Personal Data Server (PDS) hoch, lädt alle deklarierten Listing-Bilder hoch und schreibt den Release-Record.

Wenn ein kanonisches HTTPS-Repository verfügbar ist, fügt der Befehl es dem Paketprofil mit optionaler Provenienz hinzu. Profile ohne Repository-Metadaten erlauben auch Releases ohne Provenienz. Wenn profile setup das Paket so konfiguriert hat, dass es Provenienz verlangt, veröffentlichen Sie stattdessen über den generierten GitHub-Actions-Workflow.

Bundle

bundle führt build aus, validiert, sammelt Assets und erstellt einen Tarball. Im Tarball wird plugin.mjs als backend.js gepackt (der Dateiname, den die Registry erwartet).

Der Befehl akzeptiert die folgenden Flags:

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

Flag	Standard	Beschreibung
`--dir`	Aktuelles Verzeichnis	Plugin-Quellverzeichnis.
`--out-dir`, `-o`	`dist`	Ausgabeverzeichnis für den Tarball.
`--validate-only`	`false`	Überspringt den Tarball, erzeugt aber weiterhin die Artefakte in `dist/`.

Tarball-Inhalt

Datei	Erforderlich	Beschreibung
`manifest.json`	Ja	Generiertes Manifest: ID, Version, Capabilities, Hosts sowie die aus Ihrem Quellcode gelesenen Hooks und Routen. Sie pflegen es nicht von Hand.
`backend.js`	Ja	Die gebaute, in sich geschlossene Runtime-Datei (`dist/plugin.mjs`).
`README.md`	Nein	Plugin-Dokumentation.
`icon.png`	Nein	Übliches Bundle-Icon. Muss ein lesbares PNG sein; empfohlen sind 256×256.
`screenshots/`	Nein	Bis zu acht `.png`-, `.jpg`- oder `.jpeg`-Dateien; empfohlen sind 1920×1080 oder kleiner.

Validierung

bundle (und --validate-only) prüfen:

Größenlimits (RFC 0001, dekomprimiert): insgesamt ≤ 256 KB, pro Datei ≤ 128 KB, ≤ 20 Dateien. Der gzip-komprimierte Tarball ist nur ein Bruchteil davon.
Keine Node-Built-ins in backend.js — Sandbox-Code kann fs, path, child_process usw. nicht importieren. Verwenden Sie Web-APIs oder verlagern Sie diese Logik in ein natives Plugin.
Capability-Plausibilität — Namen müssen zur erkannten Menge gehören.
Kohärenz des Vertrauensvertrags — die Kreuzregeln zu network:request / allowedHosts aus Capabilities und Hosts.
Übliche Bundle-Assets — ein nicht lesbares icon.png oder ein ebensolcher Screenshot wird übersprungen. Die CLI warnt, wenn das Icon nicht 256×256 groß ist oder ein Screenshot 1920×1080 überschreitet, aber die Abmessungen allein lassen das Bundle nicht fehlschlagen. Jede enthaltene Datei zählt weiterhin zu den Limits für Dateianzahl und dekomprimierte Größe.

Um den Tarball vor dem Veröffentlichen zu prüfen, listen Sie seinen Inhalt auf:

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

Publish

Veröffentlichen Sie den aktuellen Quellcode und hosten Sie seine Artefakte auf Ihrem PDS:

emdash-plugin publish

Der folgende Manifest-Block fügt Listing-Bilder hinzu. Pfade sind relativ zu emdash-plugin.jsonc; PNG, JPEG und WebP werden unterstützt.

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

Beim Veröffentlichen wird jedes deklarierte Bild auf den PDS des Publishers hochgeladen und seine Blob-Referenz in den Release-Record geschrieben. Jedes Bild ist auf 1 MiB und 8.192 Pixel pro Seite begrenzt; ein Release kann bis zu acht Screenshots deklarieren. bundle packt außerdem das übliche icon.png sowie die PNG- und JPEG-Dateien in screenshots/ in den Tarball, unabhängig davon, ob das Manifest sie deklariert, und jede gepackte Datei zählt zu den Größenlimits von 128 KB pro Datei und 256 KB insgesamt. Legen Sie deklarierte Screenshots in einem anderen Ordner ab, etwa images/. Die vollständige Form finden Sie unter Release-Felder.

Das macht publish:

Baut das Plugin, validiert die Limits für den dekomprimierten Zustand und erstellt das gzip-Archiv.
Setzt Ihre Atmosphere-Kontositzung fort und prüft das Publisher-Pinning.
Bestätigt, dass der OAuth-Grant die Scopes für Paket- und Bild-Blobs enthält.
Lädt das Paket und die deklarierten Bilder auf Ihren PDS hoch und verifiziert dann jede zurückgegebene Blob-CID anhand der hochgeladenen Bytes.
Legt beim ersten Veröffentlichen das Paketprofil an und schreibt den unveränderlichen Release-Record.

Die CLI bezeichnet das veröffentlichte Paket als @<publisher-handle>/<slug>, gibt die öffentliche Seite aus, die nach der Freigabe verfügbar wird, und nennt einen Befehl emdash-plugin info … --version <version> --watch. Dieser Befehl liest die aktuellen Prüfungen des Labelers direkt; nicht freigegebene Paket-Metadaten fehlen weiterhin in Aggregator-Antworten und auf der öffentlichen Plugin-Website.

Wenn eine bestehende Anmeldung älter ist als die Blob-Veröffentlichung, meldet publish MISSING_BLOB_SCOPE. Führen Sie emdash-plugin logout aus und melden Sie sich dann erneut an, um die neuen Scopes zu genehmigen.

Eine externe Package-URL nutzen

Übergeben Sie --url, wenn das Paket-Bundle bereits über HTTPS verfügbar ist oder der Konto-Provider keine gzip-Blobs akzeptiert:

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

Die CLI lädt die URL herunter, validiert das ausgelieferte Bundle und berechnet seine Prüfsumme. Auf diesem Weg lädt sie den Paket-Blob nicht hoch. Listing-Bilder verwenden weiterhin PDS-Blobs.

Um die gehosteten Bytes mit einem lokalen Tarball zu vergleichen, fügen Sie --local hinzu:

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

Versionen sind standardmäßig unveränderlich

emdash-plugin publish weigert sich, ein bestehendes Release mit demselben Slug und derselben Version zu ersetzen. Erhöhen Sie version, bevor Sie erneut veröffentlichen. Der Build liest version aus package.json (siehe Nur einen Versionswert pflegen). Erhöhen Sie major bei einem erweiterten Vertrauensvertrag, minor bei neuen Hooks oder Routen und patch bei Korrekturen.

Publisher-Mismatch

Wenn publish mit MANIFEST_PUBLISHER_MISMATCH fehlschlägt, ist die aktive Sitzung ein anderes Atmosphere-Konto als der im Manifest gepinnte publisher. Wechseln Sie mit emdash-plugin switch <did> zum gepinnten Konto oder aktualisieren Sie publisher im Manifest, wenn Sie das Plugin tatsächlich auf ein neues Konto übertragen. Wie Sie Sitzungen verwalten, steht unter Ein bestehendes Konto nutzen.

Was als Nächstes lesen

Die emdash-plugin-CLI — jeder Befehl
Automatisierte Plugin-Releases — aus einem freigegebenen GitHub-Actions-Workflow veröffentlichen
Das Plugin-Manifest — Felder, Vertrauensvertrag, Publisher-Pinning
Capabilities und Sicherheit