Das Plugin-Manifest

Jedes Sandbox-Plugin hat eine Datei emdash-plugin.jsonc in seinem Stammverzeichnis. Sie liegt neben package.json, wenn das Plugin zugleich ein npm-Paket ist. Das Manifest identifiziert das Plugin, deklariert den benötigten Zugriff und Speicher und liefert Informationen für den Registry-Eintrag und die Releases. Die Plugin-CLI liest es beim Validieren, Bauen, Bündeln, Veröffentlichen und Vorbereiten automatisierter Releases.

Die Datei verwendet JSON mit Kommentaren (JSONC); Kommentare und nachgestellte Kommas sind daher gültig. Behalten Sie die von emdash-plugin init erzeugte Eigenschaft $schema bei; Editoren nutzen das generierte Schema für die Autovervollständigung, während emdash-plugin validate die vollständige Prüfung durchführt.

Das folgende Beispiel enthält jede Feldgruppe:

{
	"$schema": "./node_modules/@emdash-cms/plugin-cli/schemas/emdash-plugin.schema.json",

	"slug": "gallery",
	"publisher": "did:plc:abc123def456",

	"license": "MIT",
	"author": { "name": "Jane Doe", "url": "https://example.com" },
	"security": { "email": "[email protected]" },
	"name": "Gallery",
	"description": "Image galleries for EmDash content.",
	"keywords": ["gallery", "images"],
	"sections": {
		"installation": { "file": "./docs/installation.md" },
		"faq": { "file": "./docs/faq.md" },
	},

	"capabilities": ["content:read"],
	"allowedHosts": [],
	"storage": {
		"galleries": { "indexes": ["contentId"] },
	},

	"admin": {
		"pages": [{ "path": "/gallery", "label": "Gallery", "icon": "image" }],
	},

	"repo": "https://github.com/example/plugin-gallery",
	"release": {
		"requires": { "env:emdash": ">=0.37.0" },
		"artifacts": {
			"icon": { "file": "./images/icon.png" },
			"screenshots": [{ "file": "./images/editor.png", "lang": "en" }],
		},
	},
}

Identität und Version

Publisher und Slug identifizieren das Paket in der Registry. Der Slug wird auch in den URLs der Plugin-Routen verwendet, ist also nicht der npm-Paketname: Verwenden Sie gallery für ein Paket wie @example/plugin-gallery.

Nur einen Versionswert pflegen

Der Build gleicht version mit package.json#version ab:

• Setzen beide Dateien die Version, müssen die Werte übereinstimmen.
• Setzt nur eine Datei die Version, verwendet der Build diese.
• Setzt keine der beiden Dateien die Version, schlägt der Build fehl.

Behalten Sie bei einem npm-Paket die Version in package.json und lassen Sie sie im Manifest weg. Ein reines Registry-Plugin ohne package.json muss version im Manifest setzen.

Paketprofil

Das Paketprofil liefert die stabilen Informationen, die über alle Releases hinweg angezeigt werden.

Jeder Abschnitt kann ein Inline-String oder ein Dateiverweis relativ zum Manifest sein:

"sections": {
	"description": "A longer description written in CommonMark.",
	"installation": { "file": "./docs/installation.md" },
	"security": { "file": "./SECURITY.md" },
}

Jeder aufgelöste Abschnitt ist auf 20.000 Bytes und 2.000 Grapheme begrenzt. Ein Dateiverweis muss innerhalb des Manifestverzeichnisses bleiben; absolute Pfade und ..-Pfade, die daraus ausbrechen, werden abgelehnt.

publish legt das Paketprofil beim ersten Release an. Spätere Releases ersetzen seine Profilfelder nicht. Bearbeiten Sie ein veröffentlichtes Profil mit emdash-plugin update-package: Der Befehl zeigt die Änderungen standardmäßig nur als Vorschau an und schreibt sie nur mit --yes.

Vertrauensvertrag

Der Vertrauensvertrag besteht aus capabilities, allowedHosts und storage. Diese Felder teilen einem Betreiber mit, worauf das Plugin zugreifen kann und welche plugineigenen Collections es anlegt.

Die folgende Deklaration erlaubt Lesezugriffe auf Inhalte, erlaubt Anfragen an eine API und ihre Subdomains und legt eine Speicher-Collection an:

"capabilities": ["content:read", "network:request"],
"allowedHosts": ["api.example.com", "*.cdn.example.com"],
"storage": {
	"events": {
		"indexes": ["savedAt", ["collection", "savedAt"]],
		"uniqueIndexes": ["eventId"],
	},
}

Capabilities und Hosts

Alle drei Felder sind standardmäßig leer. Das Scaffold schreibt die leeren Werte ausdrücklich, damit ein Reviewer sehen kann, dass das Plugin keinen zusätzlichen Zugriff und keine zusätzlichen Collections anfordert.

network:request erfordert mindestens einen einfachen Hostnamen in allowedHosts. network:request:unrestricted erfordert eine leere Liste, weil es bewusst jeden öffentlichen Host erlaubt. Capabilities und Sicherheit ist die maßgebliche Referenz für jede Capability, ihre Auswirkungen, Host-Muster und die Durchsetzung zur Laufzeit.

Speicher

Jeder Schlüssel in storage benennt eine plugineigene Collection. Ihre indexes und uniqueIndexes bestimmen, nach welchen Feldern das Plugin filtern oder sortieren kann. Storage erklärt Collection-Namen, Index-Design, Abfragen und Paginierung.

Jede Änderung am Vertrauensvertrag erfordert eine neue Plugin-Version, weil installierte Sites der früheren Deklaration zugestimmt haben. Verwenden Sie für einen erweiterten Vertrag eine Major-Version.

Admin-Seiten und Widgets

Sandbox-Plugins rendern Admin-Seiten und Dashboard-Widgets mit Block Kit. Das Manifest deklariert, wo sie erscheinen:

"admin": {
	"pages": [{ "path": "/settings", "label": "Settings", "icon": "settings" }],
	"widgets": [{ "id": "recent-events", "title": "Recent events", "size": "half" }],
}

Seitenpfade beginnen mit / und enthalten Buchstaben, Ziffern, /, _ oder -. Widget-IDs verwenden dieselben kleingeschriebenen Bezeichnerzeichen wie Plugin-Slugs. Widget-Größen sind full, half oder third.

Eine Seite kann außerdem group setzen, um einem einklappbaren Ordner in der Seitenleiste beizutreten. Beim Abgleich wird zwischen Groß- und Kleinschreibung unterschieden, umgebende Leerzeichen werden ignoriert. Entspricht eine Gruppe der Gruppe einer in der Seitenleiste angezeigten Collection, wird die Seite in diesen Ordner einsortiert; Seiten, die sich eine andere Gruppe teilen – auch von unterschiedlichen Plugins –, bilden im Bereich „Plugins“ einen Ordner mit dieser Bezeichnung.

Ein Plugin, das eine Seite oder ein Widget deklariert, muss in src/plugin.ts eine Route namens admin definieren. Die Bundle-Prüfung schlägt fehl, wenn diese Route fehlt, weil EmDash dann nichts hätte, was es für die Block-Kit-Antwort aufrufen könnte.

Release-Felder

release beschreibt eine bestimmte Version. Die repo-URL auf oberster Ebene wird in Release-Einträge geschrieben und von der Einrichtung automatisierter Releases auch verwendet, um das Paketprofil an sein GitHub-Repository zu binden.

Verwenden Sie env:emdash und env:astro, um die EmDash- und Astro-Versionsbereiche festzulegen, die das Release installieren können:

"release": {
	"requires": {
		"env:emdash": ">=0.37.0",
		"env:astro": ">=5.0.0 <7.0.0",
	},
}

EmDash prüft diese Anforderungen vor der Installation. Ein ungültiger Bereich lässt die Manifestvalidierung fehlschlagen; ein inkompatibles Release wird nicht installiert.

Pfade zu Artefaktdateien sind relativ zum Manifest und müssen innerhalb seines Verzeichnisses bleiben. PNG, JPEG und WebP werden unterstützt. Jede Datei ist auf 1 MiB und 8.192 Pixel in jeder Dimension begrenzt. Eine optionale Eigenschaft lang kennzeichnet ein lokalisiertes Bild mit einem BCP-47-Sprach-Tag. Beim Veröffentlichen werden diese Dateien getrennt vom Plugin-Bundle hochgeladen; dabei werden ihr gemessener Typ, ihre Abmessungen, ihre Prüfsumme und ihre Blob-Referenz auf dem Personal Data Server (PDS) erfasst.

Publisher-Pinning

publisher verhindert versehentliches Veröffentlichen vom falschen Atmosphere-Konto. Bevorzugen Sie die DID des Kontos:

"publisher": "did:plc:abc123def456", // jane.example.com

Vor dem Veröffentlichen oder Vorbereiten automatisierter Releases vergleicht die CLI den Publisher im Manifest mit der aktiven Sitzung. Ein Handle wird für den Vergleich in seine aktuelle DID aufgelöst. Eine Abweichung schlägt mit MANIFEST_PUBLISHER_MISMATCH fehl; es gibt keinen Override-Schalter.

Ist die falsche Sitzung aktiv, führen Sie emdash-plugin whoami aus und wechseln Sie dann zum angehefteten Konto:

emdash-plugin switch did:plc:abc123def456

Ändern Sie den Publisher im Manifest nur, wenn Sie das Paket an ein anderes Konto übertragen.

Manifest validieren

Validieren Sie das Manifest, bevor Sie bauen oder veröffentlichen:

emdash-plugin validate

Übergeben Sie eine Datei oder ein Verzeichnis, um ein anderes Manifest zu validieren:

emdash-plugin validate ./packages/plugin-gallery

Die Validierung läuft offline. Sie meldet doppelte Eigenschaften, unbekannte Felder, ungültige Werte, einander ausschließende Formen und feldübergreifende Fehler wie network:request ohne eine nicht leere Liste allowedHosts.

Weiter geht es mit der Plugin-CLI für Build-Befehle oder mit Bündeln und Veröffentlichen für den Release-Ablauf.