Le manifeste du plugin

Chaque plugin en sandbox possède un emdash-plugin.jsonc à côté de son package.json. Il est édité manuellement et contient l’identité du plugin, son contrat de confiance (capabilities, hosts, storage) et les champs de profil que le registre affiche. emdash-plugin init en crée un ; le CLI lit ./emdash-plugin.jsonc automatiquement pour build, dev, validate, bundle et publish.

Le fichier est en JSONC : les commentaires et les virgules finales sont autorisés.

L’exemple suivant montre un manifeste complet pour un plugin de galerie d’images :

{
	"$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]" },

	// Optional profile
	"name": "Gallery",
	"description": "Image gallery block for EmDash.",
	"keywords": ["gallery", "images"],
	"repo": "https://github.com/example/plugin-gallery",

	// Trust contract
	"capabilities": ["content:read"],
	"allowedHosts": [],
	"storage": {}
}

Identité

slug et publisher ensemble forment l’identité du package. EmDash dérive l’identifiant complet du package automatiquement à partir d’eux.

version se trouve dans package.json

Le build réconcilie la version du manifeste avec package.json#version :

• Les deux définis et égaux → correct.
• Les deux définis et différents → erreur critique.
• Un seul défini → cette valeur l’emporte.
• Aucun défini → erreur critique.

Le modèle recommandé pour un plugin distribué via npm est d’omettre version du manifeste et de laisser package.json être la seule source de vérité (vos outils de release l’incrémentent déjà là-bas). Les plugins uniquement pour le registre sans package.json doivent définir version dans le manifeste — il n’y a pas d’autre endroit pour elle.

Profil

Ceux-ci alimentent la liste du registre. license, un auteur (author ou authors) et un contact de sécurité (security ou securityContacts) sont requis ; le reste est optionnel.

Utilisez la forme singulière author / security sauf si vous avez véritablement plusieurs — c’est le cas courant et le scaffold l’émet.

Contrat de confiance

Le contrat de confiance est capabilities, allowedHosts et storage. Tous trois sont vides par défaut, donc un plugin qui ne nécessite pas de privilèges supplémentaires peut les omettre entièrement.

{
	"capabilities": ["network:request", "content:read"],
	"allowedHosts": ["api.example.com", "*.cdn.example.com"],
	"storage": {
		"events": { "indexes": ["timestamp"] },
		"submissions": { "indexes": ["email"], "uniqueIndexes": ["token"] }
	}
}

Capabilities

Les noms reconnus :

Deux règles inter-champs que le CLI applique (la vérification JSON-Schema de l’éditeur ne le fait pas — exécutez emdash-plugin validate) :

• network:request nécessite un allowedHosts non vide. Si le plugin doit vraiment atteindre n’importe quel hôte, utilisez network:request:unrestricted à la place.
• network:request:unrestricted nécessite que allowedHosts soit vide — la capability sans restriction accorde déjà tous les hôtes, donc une liste la contredirait.

Les modèles d’hôtes sont des noms d’hôtes simples (pas de schéma, chemin ou espace blanc). Un *. initial autorise les sous-domaines : *.cdn.example.com.

Storage

Une carte de nom de collection → configuration d’index. Les noms de collection suivent la même règle /^[a-z][a-z0-9_]*$/ (le runtime utilise le nom comme suffixe de table SQL). Les index sont des noms de champs ou des tableaux composites ; uniqueIndexes sont également interrogeables — ne les listez pas aussi dans indexes.

"storage": {
	"events": { "indexes": ["timestamp", ["collection", "timestamp"]] }
}

Surface d’administration

Optionnel. Les plugins en sandbox rendent les pages d’administration et les widgets de tableau de bord via Block Kit ; le manifeste déclare seulement où ils apparaissent. Omettez entièrement la clé admin si le plugin n’a pas d’UI d’administration.

"admin": {
	"pages": [{ "path": "/gallery", "label": "Gallery", "icon": "image" }],
	"widgets": [{ "id": "recent-uploads", "title": "Recent uploads", "size": "half" }]
}

Un plugin qui déclare admin.pages ou admin.widgets doit également servir une route admin dans src/plugin.ts qui rend le contenu Block Kit — le schema ne peut pas l’imposer (les noms de routes sont sondés depuis la source, pas depuis le manifeste), mais le runtime le vérifie.

Épinglage de publisher

publisher épingle l’identité de publication pour que vous ne puissiez pas accidentellement publier un plugin sous le mauvais compte.

Lors de votre première publication réussie, si le publisher du manifeste correspond à la session active, il reste tel qu’écrit. Si vous avez créé un scaffold avec emdash-plugin init et l’avez laissé vide, le CLI réécrit le DID de la session active dans le manifeste.

L’exemple suivant montre la ligne que le CLI écrit, avec le handle résolu ajouté en commentaire pour la lisibilité :

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

À chaque publication ultérieure, le CLI résout la session active et le publisher épinglé en DIDs et les compare. Une non-correspondance échoue immédiatement avec MANIFEST_PUBLISHER_MISMATCH — il n’y a pas de flag de remplacement. Résolvez-le délibérément :

• Mauvaise session : emdash-plugin switch <did>, puis publiez à nouveau.
• Transfert véritable du plugin à un nouveau publisher : modifiez publisher dans le manifeste.

Valider sans publier

emdash-plugin validate          # ./emdash-plugin.jsonc
emdash-plugin validate path/    # un répertoire spécifique

Vérification de schema hors ligne avec des diagnostics de style tsc file:line:column, incluant les règles inter-champs. Adapté à un hook pre-commit ou une étape CI. Les clés dupliquées et clés inconnues sont des erreurs (le mode strict attrape les fautes de frappe "licens").

Les flags CLI l’emportent toujours

Les flags explicites (--license, --author-name, …) remplacent les valeurs du manifeste lorsque les deux sont définis — utile pour les remplacements CI. --no-manifest ignore entièrement le manifeste (et avertit si un existe au chemin par défaut, de sorte que l’histoire de sécurité de l’épinglage du publisher reste visible).

Suivant

• Le CLI emdash-plugin
• Empaquetage et publication
• Capabilities et sécurité