Il manifesto del plugin

Ogni plugin in sandbox ha un file emdash-plugin.jsonc nella propria directory radice. Si trova accanto a package.json quando il plugin è anche un pacchetto npm. Il manifesto identifica il plugin, dichiara l’accesso e l’archiviazione di cui ha bisogno e fornisce le informazioni per la sua scheda nel registro e per le sue release. La CLI dei plugin lo legge durante la convalida, la build, il bundling, la pubblicazione e la preparazione delle release automatizzate.

Il file usa JSON con commenti (JSONC), quindi commenti e virgole finali sono validi. Mantieni la proprietà $schema creata da emdash-plugin init; gli editor usano lo schema generato per il completamento automatico, mentre emdash-plugin validate esegue il controllo completo.

L’esempio seguente include ogni gruppo di campi:

{
	"$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à e versione

Il publisher e lo slug identificano il pacchetto nel registro. Lo slug è usato anche negli URL delle route del plugin, quindi non è il nome del pacchetto npm: usa gallery per un pacchetto come @example/plugin-gallery.

Mantieni un solo valore di versione

La build riconcilia version con package.json#version:

• Se entrambi i file impostano la versione, i valori devono coincidere.
• Se un solo file imposta la versione, la build usa quella.
• Se nessuno dei due file imposta la versione, la build non riesce.

Per un pacchetto npm, mantieni la versione in package.json e omettila dal manifesto. Un plugin solo per il registro, senza package.json, deve impostare version nel manifesto.

Profilo del pacchetto

Il profilo del pacchetto fornisce le informazioni stabili mostrate in tutte le release.

Ogni sezione può essere una stringa inline o un riferimento a un file relativo al manifesto:

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

Ogni sezione risolta è limitata a 20.000 byte e 2.000 grafemi. Un riferimento a un file deve restare all’interno della directory del manifesto; i percorsi assoluti e quelli con .. che ne escono vengono rifiutati.

publish crea il profilo del pacchetto alla prima release. Le release successive non sostituiscono i suoi campi di profilo. Modifica un profilo pubblicato con emdash-plugin update-package: per impostazione predefinita il comando mostra un’anteprima delle modifiche e le scrive solo con --yes.

Contratto di fiducia

Il contratto di fiducia è composto da capabilities, allowedHosts e storage. Questi campi indicano a un operatore a cosa può accedere il plugin e quali collection di sua proprietà crea.

La dichiarazione seguente consente le letture dei contenuti, consente le richieste a un’API e ai suoi sottodomini e crea una collection di archiviazione:

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

Capability e host

Tutti e tre i campi sono vuoti per impostazione predefinita. Lo scaffold scrive esplicitamente i valori vuoti, così chi revisiona può vedere che il plugin non richiede accessi o collection aggiuntivi.

network:request richiede almeno un hostname semplice in allowedHosts. network:request:unrestricted richiede un elenco vuoto perché consente deliberatamente qualsiasi host pubblico. Capability e sicurezza è il riferimento canonico per ogni capability, le sue implicazioni, i pattern degli host e l’applicazione a runtime.

Archiviazione

Ogni chiave in storage indica una collection di proprietà del plugin. I suoi indexes e uniqueIndexes determinano per quali campi il plugin può filtrare o ordinare. Storage spiega i nomi delle collection, la progettazione degli indici, le query e la paginazione.

Modificare una qualsiasi parte del contratto di fiducia richiede una nuova versione del plugin, perché i siti installati hanno acconsentito alla dichiarazione precedente. Usa una versione major per un contratto ampliato.

Pagine di amministrazione e widget

I plugin in sandbox renderizzano pagine di amministrazione e widget della dashboard con Block Kit. Il manifesto dichiara dove compaiono:

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

I percorsi delle pagine iniziano con / e contengono lettere, cifre, /, _ o -. Gli ID dei widget usano gli stessi caratteri minuscoli per gli identificatori degli slug dei plugin. Le dimensioni dei widget sono full, half o third.

Una pagina può anche impostare group per unirsi a una cartella comprimibile della barra laterale. La corrispondenza distingue tra maiuscole e minuscole e gli spazi circostanti vengono ignorati. Un gruppo che corrisponde al gruppo di una collezione mostrata nella barra laterale colloca la pagina in quella cartella; le pagine che condividono qualsiasi altro gruppo, di qualsiasi plugin, formano una cartella con quell’etichetta nella sezione Plugin.

Un plugin che dichiara una pagina o un widget deve definire una route chiamata admin in src/plugin.ts. Il controllo del bundle non riesce se questa route manca, perché EmDash non avrebbe nulla da chiamare per ottenere la risposta Block Kit.

Campi della release

release descrive una versione specifica. L’URL repo di primo livello viene scritto nei record della release ed è usato anche dalla configurazione delle release automatizzate per collegare il profilo del pacchetto al suo repository GitHub.

Usa env:emdash e env:astro per impostare gli intervalli di versione di EmDash e Astro che possono installare la release:

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

EmDash controlla questi requisiti prima dell’installazione. Un intervallo non valido fa fallire la convalida del manifesto; una release incompatibile non viene installata.

I percorsi dei file degli artefatti sono relativi al manifesto e devono restare all’interno della sua directory. Sono supportati PNG, JPEG e WebP. Ogni file è limitato a 1 MiB e a 8.192 pixel per ciascuna dimensione. Una proprietà facoltativa lang identifica un’immagine localizzata con un tag di lingua BCP 47. La pubblicazione carica questi file separatamente dal bundle del plugin e registra il loro tipo misurato, le dimensioni, il checksum e il riferimento blob sul personal data server (PDS).

Pinning del publisher

publisher evita una pubblicazione accidentale dall’account Atmosphere sbagliato. Preferisci il DID dell’account:

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

Prima di pubblicare o di preparare le release automatizzate, la CLI confronta il publisher del manifesto con la sessione attiva. Un handle viene risolto nel suo DID attuale per il confronto. Una discrepanza fallisce con MANIFEST_PUBLISHER_MISMATCH; non esiste alcun flag per forzare.

Se è attiva la sessione sbagliata, esegui emdash-plugin whoami, poi passa all’account fissato:

emdash-plugin switch did:plc:abc123def456

Cambia il publisher del manifesto solo quando trasferisci il pacchetto a un altro account.

Convalidare il manifesto

Convalida il manifesto prima di fare la build o di pubblicare:

emdash-plugin validate

Passa un file o una directory per convalidare un manifesto diverso:

emdash-plugin validate ./packages/plugin-gallery

La convalida avviene offline. Segnala proprietà duplicate, campi sconosciuti, valori non validi, forme che si escludono a vicenda ed errori tra più campi, come network:request senza un elenco allowedHosts non vuoto.

Prosegui con la CLI dei plugin per i comandi di build o con Bundle e pubblicazione per il flusso di release.