Le manifeste du plugin

Chaque plugin en sandbox possède un fichier emdash-plugin.jsonc à la racine de son répertoire. Il se trouve à côté de package.json lorsque le plugin est aussi un paquet npm. Le manifeste identifie le plugin, déclare l’accès et le stockage dont il a besoin et fournit les informations pour sa fiche dans le registre et pour ses versions. La CLI de plugins le lit lors de la validation, de la construction, du bundling, de la publication et de la préparation des versions automatisées.

Le fichier utilise JSON avec commentaires (JSONC) : les commentaires et les virgules finales sont donc valides. Conservez la propriété $schema créée par emdash-plugin init ; les éditeurs utilisent le schéma généré pour l’autocomplétion, tandis que emdash-plugin validate effectue la vérification complète.

L’exemple suivant comprend chaque groupe de champs :

{
	"$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é et version

Le publisher et le slug identifient le paquet dans le registre. Le slug sert aussi dans les URL des routes du plugin ; ce n’est donc pas le nom du paquet npm : utilisez gallery pour un paquet tel que @example/plugin-gallery.

Conserver une seule valeur de version

Le build concilie version avec package.json#version :

• Si les deux fichiers définissent la version, les valeurs doivent correspondre.
• Si un seul fichier définit la version, le build l’utilise.
• Si aucun des deux fichiers ne définit la version, le build échoue.

Pour un paquet npm, conservez la version dans package.json et omettez-la du manifeste. Un plugin réservé au registre, sans package.json, doit définir version dans le manifeste.

Profil du paquet

Le profil du paquet fournit les informations stables affichées d’une version à l’autre.

Chaque section peut être une chaîne en ligne ou une référence de fichier relative au manifeste :

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

Chaque section résolue est limitée à 20 000 octets et 2 000 graphèmes. Une référence de fichier doit rester à l’intérieur du répertoire du manifeste ; les chemins absolus et les chemins .. qui en sortent sont rejetés.

publish crée le profil du paquet lors de la première version. Les versions suivantes ne remplacent pas ses champs de profil. Modifiez un profil publié avec emdash-plugin update-package : par défaut, la commande affiche un aperçu des changements et ne les écrit qu’avec --yes.

Contrat de confiance

Le contrat de confiance se compose de capabilities, allowedHosts et storage. Ces champs indiquent à un opérateur à quoi le plugin peut accéder et quelles collections qui lui appartiennent il crée.

La déclaration suivante autorise les lectures de contenu, autorise les requêtes vers une API et ses sous-domaines, et crée une collection de stockage :

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

Capabilities et hôtes

Les trois champs sont vides par défaut. Le scaffold écrit explicitement les valeurs vides afin qu’un relecteur voie que le plugin ne demande ni accès ni collections supplémentaires.

network:request exige au moins un nom d’hôte simple dans allowedHosts. network:request:unrestricted exige une liste vide, car il autorise délibérément n’importe quel hôte public. Capabilities et sécurité est la référence canonique pour chaque capability, ses implications, les modèles d’hôtes et l’application à l’exécution.

Stockage

Chaque clé de storage désigne une collection propre au plugin. Ses indexes et uniqueIndexes déterminent selon quels champs le plugin peut filtrer ou trier. Stockage explique les noms de collections, la conception des index, les requêtes et la pagination.

Modifier une partie quelconque du contrat de confiance exige une nouvelle version du plugin, car les sites installés ont consenti à la déclaration précédente. Utilisez une version majeure pour un contrat élargi.

Pages d’administration et widgets

Les plugins en sandbox affichent des pages d’administration et des widgets de tableau de bord avec Block Kit. Le manifeste déclare où ils apparaissent :

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

Les chemins de page commencent par / et contiennent des lettres, des chiffres, /, _ ou -. Les ID de widget utilisent les mêmes caractères d’identifiant en minuscules que les slugs de plugin. Les tailles de widget sont full, half ou third.

Une page peut aussi définir group pour rejoindre un dossier repliable de la barre latérale. La correspondance est sensible à la casse et les espaces environnants sont ignorés. Un groupe qui correspond au groupe d’une collection affichée dans la barre latérale place la page dans ce dossier ; les pages qui partagent tout autre groupe, quel que soit le plugin, forment un dossier portant cette étiquette dans la section Plugins.

Un plugin qui déclare une page ou un widget doit définir une route nommée admin dans src/plugin.ts. La vérification du bundle échoue si cette route est absente, car EmDash n’aurait rien à appeler pour obtenir la réponse Block Kit.

Champs de release

release décrit une version particulière. L’URL repo de premier niveau est écrite dans les enregistrements de release, et la configuration des releases automatisées l’utilise aussi pour lier le profil du paquet à son dépôt GitHub.

Utilisez env:emdash et env:astro pour définir les plages de versions d’EmDash et d’Astro qui peuvent installer la release :

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

EmDash vérifie ces exigences avant l’installation. Une plage invalide fait échouer la validation du manifeste ; une release incompatible n’est pas installée.

Les chemins des fichiers d’artefacts sont relatifs au manifeste et doivent rester à l’intérieur de son répertoire. Les formats PNG, JPEG et WebP sont pris en charge. Chaque fichier est limité à 1 Mio et à 8 192 pixels dans chaque dimension. Une propriété facultative lang identifie une image localisée par une balise de langue BCP 47. La publication téléverse ces fichiers séparément du bundle du plugin et enregistre leur type mesuré, leurs dimensions, leur somme de contrôle et leur référence de blob sur le serveur de données personnelles (PDS).

Épinglage du publisher

publisher évite une publication accidentelle depuis le mauvais compte Atmosphere. Privilégiez le DID du compte :

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

Avant de publier ou de préparer des releases automatisées, la CLI compare le publisher du manifeste avec la session active. Un handle est résolu en son DID actuel pour la comparaison. Une différence échoue avec MANIFEST_PUBLISHER_MISMATCH ; il n’existe aucune option de contournement.

Si la mauvaise session est active, exécutez emdash-plugin whoami, puis passez au compte épinglé :

emdash-plugin switch did:plc:abc123def456

Ne modifiez le publisher du manifeste que lorsque vous transférez le paquet vers un autre compte.

Valider le manifeste

Validez le manifeste avant de construire ou de publier :

emdash-plugin validate

Passez un fichier ou un répertoire pour valider un autre manifeste :

emdash-plugin validate ./packages/plugin-gallery

La validation se fait hors ligne. Elle signale les propriétés en double, les champs inconnus, les valeurs invalides, les formes mutuellement exclusives et les erreurs entre champs, comme network:request sans liste allowedHosts non vide.

Poursuivez avec la CLI de plugins pour les commandes de build ou avec Empaqueter et publier pour le flux de publication.