Bündeln und Veröffentlichen | EmDash CMS Everything

Veröffentlichen Sie ein funktionierendes sandboxed Plugin, damit andere Sites es installieren können. Veröffentlichen ist nur sandboxed — native Plugins verteilen sich über npm.

Veröffentlichen Sie direkt über die CLI, oder nutzen Sie den automatisierten Release-Dienst, um aus GitHub Actions zu bauen und zu veröffentlichen. Beide Wege schreiben das Release in Ihr Atmosphere-Konto. Sie brauchen nur dann einen separaten Artefakt-Host, wenn Sie explizit den --url-Pfad der direkten CLI wählen.

Voraussetzungen

Ein gültiges emdash-plugin.jsonc mit slug, publisher, license, einem Autor (author oder authors) und einem Security-Kontakt (security oder securityContacts). Führen Sie emdash-plugin validate zur Bestätigung aus.
Eine version (in package.json, oder dem Manifest für registry-only Plugins).
Ein Atmosphere-Konto, unter dem veröffentlicht wird.

Eine Veröffentlichungsmethode wählen

Beide Methoden erzeugen publisher-eigene Package- und Release-Records. Wählen Sie, wo der Release-Build laufen soll und welche Credential ihn autorisieren soll.

Methode	Nutzen Sie sie, wenn	Kontozugriff
`emdash-plugin publish`	Sie von Ihrem Computer oder einer anderen vertrauenswürdigen Umgebung bauen und veröffentlichen.	Die lokale CLI-Sitzung schreibt Package-Profil, Release und Blobs.
Automatisierte Releases	GitHub Actions Releases aus Versions-Tags oder manuellen Workflow-Läufen bauen soll.	Die lokale CLI bereitet das Profil vor; der Release-Dienst behält create-only Release- und Blob-Autorität.

Ihr Atmosphere-Konto

Sie veröffentlichen unter einem Atmosphere-Konto: einer portablen, nutzereigenen Identität, die über Bluesky und andere Apps im AT Protocol-Netzwerk verwendet wird. Ein Konto ist Ihr einziges Login im Netzwerk, mit demselben @handle überall, und Ihre Identität und Daten sind an keine 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, als Sie signiert.

EmDash nutzt dieselben Atmosphere-Konten wie sein Atmosphere-Login für Sites.

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

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

Ein Konto erstellen

Wenn Sie noch kein Atmosphere-Konto haben, erstellen Sie eines über einen Anbieter und führen Sie dann emdash-plugin login <your-handle> aus. Ihre Optionen:

Eine App wie Bluesky. Die Anmeldung bei Bluesky erzeugt ein von Bluesky gehostetes Atmosphere-Konto. Das ist der schnellste Weg.
Ein unabhängiger Anbieter. Community- oder privacy-orientierte Kontenhosts. Optionen unter atmosphereaccount.com.
Self-hosted. Betreiben Sie Ihren eigenen Anbieter für volle Kontrolle über Identität und Daten.

Welches Sie auch wählen: Der @handle dieses Kontos ist, was Sie an emdash-plugin login übergeben, und die DID des Kontos ist, was Sie als publisher im Manifest festnageln.

Aus Ihrem Plugin-Verzeichnis veröffentlichen

Melden Sie sich einmal an und veröffentlichen Sie dann aus dem Verzeichnis mit emdash-plugin.jsonc:

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

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

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

Bundle

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

Der Befehl akzeptiert folgende Flags:

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

Flag	Default	Beschreibung
`--dir`	Aktuelles Verzeichnis	Plugin-Quellverzeichnis.
`--out-dir`, `-o`	`dist`	Ausgabeverzeichnis für das Tarball.
`--validate-only`	`false`	Tarball überspringen, aber trotzdem `dist/`-Artefakte erzeugen.

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 das nicht von Hand.
`backend.js`	Ja	Die gebaute, in sich geschlossene Runtime-Datei (`dist/plugin.mjs`).
`README.md`	Nein	Plugin-Dokumentation.
`icon.png`	Nein	Konventionelles Bundle-Icon. Muss ein lesbares PNG sein; 256×256 wird empfohlen.
`screenshots/`	Nein	Bis zu acht `.png`-, `.jpg`- oder `.jpeg`-Dateien; 1920×1080 oder kleiner wird empfohlen.

Validierung

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

Größenlimits (RFC 0001, dekomprimiert): gesamt ≤ 256 KB, pro Datei ≤ 128 KB, ≤ 20 Dateien. Das gzippte Tarball ist ein Bruchteil davon.
Keine Node-Built-ins in backend.js — Sandbox-Code darf fs, path, child_process usw. nicht importieren. Nutzen Sie Web-APIs oder verlagern Sie diese Logik in ein natives Plugin.
Capability-Sanity — Namen müssen im anerkannten Satz liegen.
Trust-Contract-Kohärenz — die network:request / allowedHosts-Kreuzregeln aus Capabilities und Hosts.
Konventionelle Bundle-Assets — ein unlesbares icon.png oder Screenshot wird übersprungen. Die CLI warnt, wenn das Icon nicht 256×256 ist oder ein Screenshot 1920×1080 überschreitet, aber Dimensionen allein lassen das Bundle nicht scheitern. Jede enthaltene Datei zählt weiterhin zu den Datei- und dekomprimierten Größenlimits.

Um das 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": "./screenshots/editor.png" },
        { "file": "./screenshots/settings.jpg", "lang": "en" }
      ]
    }
  }
}

Im Manifest deklarierte Listing-Bilder sind getrennt von den konventionellen icon.png- und screenshots/-Dateien im Tarball. Das Veröffentlichen lädt jedes deklarierte Bild auf den PDS des Publishers hoch und schreibt seine Blob-Referenz in den Release-Record. Jedes Bild ist auf 1 MiB und 8.192 Pixel in jeder Dimension begrenzt; ein Release kann bis zu acht Screenshots deklarieren. Siehe Release-Felder für die vollständige Form.

Was publish tut:

Baut das Plugin, validiert die dekomprimierten Limits und erzeugt das Gzip-Archiv.
Nimmt Ihre Atmosphere-Konto-Sitzung wieder auf und prüft Publisher-Pinning.
Bestätigt, dass der OAuth-Grant Package- und Bild-Blob-Scopes enthält.
Lädt Package und deklarierte Bilder auf Ihren PDS hoch und verifiziert jede zurückgegebene Blob-CID gegen die hochgeladenen Bytes.
Erzeugt das Package-Profil beim ersten Publish und schreibt den unveränderlichen Release-Record.

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

Wenn ein bestehendes Login vor Blob-Publishing liegt, meldet publish MISSING_BLOB_SCOPE. Führen Sie emdash-plugin logout aus und melden Sie sich erneut an, um die neuen Scopes zu genehmigen.

Eine externe Package-URL nutzen

Übergeben Sie --url, wenn das Package-Bundle bereits über HTTPS verfügbar ist oder der Kontenanbieter Gzip-Blobs nicht 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 Pfad lädt sie den Package-Blob nicht hoch. Listing-Bilder nutzen 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 unter demselben Slug und derselben Version zu ersetzen. Erhöhen Sie version, bevor Sie erneut veröffentlichen. Der Build liest version aus package.json (siehe Einen Versionswert behalten). Erhöhen Sie major für einen erweiterten Trust-Contract, minor für neue Hooks oder Routen und patch für Fixes.

Publisher-Mismatch

Wenn publish mit MANIFEST_PUBLISHER_MISMATCH scheitert, ist die aktive Sitzung ein anderes Atmosphere-Konto als der gepinnte publisher des Manifests. Wechseln Sie mit emdash-plugin switch <did> zum gepinnten Konto, oder aktualisieren Sie publisher im Manifest, wenn Sie das Plugin wirklich an ein neues Konto übertragen. Siehe Ein bestehendes Konto nutzen zur Verwaltung von Sitzungen.

Was als Nächstes lesen

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