La CLI `emdash-plugin` | EmDash CMS Everything

@emdash-cms/plugin-cli génère, construit, valide et publie des plugins isolés (sandboxed). Elle gère aussi la connexion de l’éditeur, les profils de paquet, la découverte du registre et les publications automatisées. Le binaire installé est emdash-plugin.

La CLI utilise un compte Atmosphere comme identité d’éditeur pour les profils de paquet et les publications.

Installer la CLI

Les plugins créés avec pnpm dlx @emdash-cms/plugin-cli init incluent déjà la CLI comme dépendance de développement épinglée. Ajoutez-la à un plugin existant avant d’utiliser les autres commandes :

pnpm add -D @emdash-cms/plugin-cli

Les exemples utilisent pnpm exec emdash-plugin pour que chaque commande exécute la version installée dans le plugin. Utilisez pnpm dlx pour la commande init ponctuelle, pas pour les commandes répétées de build, login ou release.

Commandes

La CLI fournit les commandes suivantes :

emdash-plugin init [name]                    Scaffold a new sandboxed plugin
emdash-plugin build                          Build dist/ (plugin.mjs, manifest.json, index.mjs)
emdash-plugin dev                            Watch sources and rebuild on change
emdash-plugin bundle                         Pack dist/ + assets into a registry tarball
emdash-plugin validate [path]                Validate emdash-plugin.jsonc against the schema
emdash-plugin publish                        Build, upload, and publish a release
emdash-plugin update-package [--yes]         Preview or apply package-profile changes
emdash-plugin profile setup                  Prepare the signed package profile for delegated releases
emdash-plugin release setup                  Create the delegated-release GitHub Actions workflow
emdash-plugin release plan                   Plan repository releases for GitHub Actions
emdash-plugin release prepare <slug[@ver]>   Prepare one repository package for GitHub Actions
emdash-plugin login <handle-or-did>          Sign in with your Atmosphere account
emdash-plugin logout [--did <did>]           Revoke the active session
emdash-plugin whoami                         Show stored sessions
emdash-plugin switch <did>                   Switch the active publisher session
emdash-plugin search <query>                 Free-text registry search
emdash-plugin info <handle-or-did> <slug>    Show package details or listing-check status

Exécutez emdash-plugin <command> --help pour les arguments et flags actuels. Les commandes destinées aux scripts, notamment validate, publish, update-package, search, info, login et whoami, fournissent une sortie JSON lorsque leur aide liste --json. Les commandes de découverte acceptent --registry-url <url> ou la variable d’environnement EMDASH_REGISTRY_URL.

La sortie lisible identifie les paquets du registre comme @<publisher-handle>/<slug>. Un nom de paquet npm est étiqueté npm package lorsque les diagnostics de build doivent l’afficher.

L’exemple suivant montre les deux scripts que la plupart des plugins ajoutent à package.json :

{
	"scripts": {
		"build": "emdash-plugin build",
		"dev": "emdash-plugin dev"
	}
}

`init`

Créez un nouveau plugin avec init :

pnpm dlx @emdash-cms/plugin-cli init my-plugin

Cela génère emdash-plugin.jsonc, src/plugin.ts, package.json, tsconfig.json, vitest.config.ts, un test basé sur workerd, un README, AGENTS.md, un skill local creating-plugins et la configuration du gestionnaire de paquets. .agents/skills et .claude/skills pointent vers le répertoire canonique skills, et .claude/CLAUDE.md pointe vers AGENTS.md, pour que Codex et Claude utilisent les mêmes conseils de projet. Le code source commence par une route assignée à une constante typée SandboxedPlugin et exportée par défaut. Le test invoque cette route via le wrapper sandbox de production et le pont hôte d’EmDash.

La configuration interactive demande l’éditeur, l’auteur, le contact de sécurité et le dépôt source, puis affiche le résumé complet du projet avant d’écrire. Les champs obligatoires ne peuvent pas être ignorés.

La CLI détecte si npm, pnpm, Yarn ou Bun l’a lancée et génère des commandes correspondantes. Remplacez le choix avec --package-manager. Un scaffold pnpm inclut la politique de scripts de build revue nécessaire à esbuild.

La configuration non interactive exige des métadonnées de propriété explicites. Utilisez la forme suivante dans les scripts :

pnpm dlx @emdash-cms/plugin-cli init my-plugin --yes \
  --publisher did:plc:abc123def456 \
  --author-name "Jane Doe" \
  --security-email security@example.com

Passez --use-detected pour utiliser la session d’éditeur active et les métadonnées locales d’auteur ou de dépôt Git. Sans ce flag, --yes ne copie pas les valeurs par défaut locales portant une identité.

`build`

build lit emdash-plugin.jsonc, src/plugin.ts et un package.json frère optionnel, et émet les fichiers suivants :

Artifact	What it is
`dist/plugin.mjs` (+ `dist/plugin.d.mts`)	Les hooks et routes. Chargés en processus (`plugins: []`) et par le chargeur sandbox (`sandboxed: []`).
`dist/manifest.json`	Le manifeste du plugin, y compris les hooks et routes lus depuis `src/plugin.ts`. `bundle` inclut ce fichier tel quel ; les consommateurs npm le lisent sans analyser la source JSONC.
`dist/index.mjs` (+ `dist/index.d.mts`)	Le module descripteur qu’un site importe dans `astro.config.mjs`. Émis seulement lorsqu’un `package.json` frère existe ; les plugins uniquement registre l’omettent, car rien ne l’importe.

dist/ est une sortie de build. Ne le committez pas. Le .gitignore du scaffold l’exclut. Exécutez emdash-plugin build avant d’empaqueter ou de publier le paquet npm pour que sa liste files ait les artefacts générés.

`dev`

Surveille src/**, emdash-plugin.jsonc et package.json, avec un debounce de rebuilds à 150 ms. Les rebuilds sont sérialisés. Sur un rebuild échoué, il laisse le dernier bon dist/ en place, pour qu’un site important le plugin via un lien workspace/file continue de fonctionner jusqu’au prochain build réussi. Ctrl-C se termine proprement.

Développez contre un vrai site en exécutant pnpm dev dans le répertoire du plugin et en l’installant dans le site avec pnpm add file:../path/to/plugin. Importez l’export par défaut du plugin dans emdash({ sandboxed: [...] }). Le first-plugin tutorial montre la configuration complète.

`validate`

Validez le manifeste du répertoire courant, ou passez un autre répertoire de plugin :

emdash-plugin validate          # ./emdash-plugin.jsonc
emdash-plugin validate path/    # a specific directory

Vérification de schéma hors ligne avec des diagnostics style tsc file:line:column, y compris les règles inter-champs du manifeste. Pas de réseau. Bon comme gate pre-commit ou CI. Voir the manifest reference.

`bundle`

bundle est une étape d’empaquetage légère au-dessus de build :

Exécute build pour produire dist/.
Valide le bundle : pas d’imports de builtins Node, pas de fichiers trop gros, sanity des capacités.
Collecte les assets optionnels — README, icône, captures.
Crée un tarball. Dans le tarball, plugin.mjs est empaqueté en backend.js (le nom de fichier attendu par le registre). La sortie est dist/<slug>-<version>.tar.gz.

--validate-only saute la création du tarball mais produit toujours les artefacts dist/ — « validate » implique « build d’abord ».

`publish`

publish construit et valide le plugin, téléverse le paquet et les images de listing vers votre PDS, puis écrit l’enregistrement de publication.

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

publish lit le manifeste pour les champs de profil et applique le publisher pinning. Conservez la licence, l’auteur, le contact de sécurité et les autres informations du paquet dans le manifeste. Les anciens flags de profil et --no-manifest restent disponibles pour la publication scriptée legacy ; consultez publish --help avant de maintenir un de ces flux.

Passez --url <https-url> pour utiliser un bundle de paquet hébergé en externe. La CLI télécharge et valide l’URL avant de publier. Ajoutez --local <path> pour vérifier qu’un tarball local correspond aux octets téléchargés.

Suivez Bundling and publishing pour le flux de publication local complet.

`info`

info affiche les détails du paquet approuvé depuis l’agrégateur. Après publication, passez la version de publication et --watch pour suivre les contrôles actuels de profil et de listing de publication :

emdash-plugin info plugins.emdashcms.com audit-log --version 0.2.2 --watch

Avant l’approbation, la commande lit le statut directement depuis le labeler et n’affiche que l’identifiant du paquet et l’état du contrôle. Elle ne renvoie pas de métadonnées de paquet non approuvées depuis l’agrégateur. Une fois le paquet et la publication publics, elle affiche les détails approuvés et l’URL canonique de la page du plugin. Arrêtez la surveillance avec Ctrl-C sans affecter les enregistrements publiés ni les contrôles de listing.

Utilisez --labeler-url <origin> ou EMDASH_LABELER_URL pour vérifier un registre qui utilise un autre labeler.

`update-package`

Utilisez update-package pour modifier un profil de paquet existant sans créer de publication. Elle lit les champs de profil dans emdash-plugin.jsonc, récupère le profil signé actuel et affiche les changements proposés :

emdash-plugin update-package

La commande est un dry run sauf si vous passez --yes :

emdash-plugin update-package --yes

L’écriture utilise le CID d’enregistrement actuel comme précondition. Si un autre processus modifie le profil après la lecture par la commande, la mise à jour échoue avec STALE_RECORD au lieu d’écraser l’enregistrement plus récent. Retirer une propriété optionnelle du manifeste laisse sa valeur publiée inchangée ; définissez explicitement le remplacement prévu.

`profile setup`

profile setup prépare le profil de paquet appartenant à l’éditeur pour les publications automatisées. Elle crée un profil manquant depuis emdash-plugin.jsonc, ou ajoute des réglages de publication déléguée à un profil valide existant sans remplacer ses métadonnées de paquet.

Exécutez la configuration interactive depuis le répertoire du plugin. Depuis ailleurs dans un monorepo, passez --dir <plugin-directory> :

emdash-plugin profile setup

Flag	Default	Description
`--dir <path>`	Répertoire courant	Répertoire source du plugin.
`--repository <url>`	`repo` du manifeste, puis `origin` Git	URL canonique du dépôt GitHub public. La configuration interactive préremplit un remote GitHub détecté ou demande s’il n’y en a pas.
`--provenance <mode>`	`required`	Utilisez `required` pour les publications avec provenance ou `optional` pour autoriser les publications locales sans provenance. La configuration interactive demande.
`--confirmation <mode>`	`escalation-only`	Utilisez `escalation-only` pour les augmentations de permission ou `always` pour chaque publication.
`--yes`, `-y`	`false`	Accepter la politique par défaut sans demander. Requis lorsqu’une exécution non interactive modifierait le profil.

La commande utilise la connexion CLI active pour écrire le profil. Elle refuse de remplacer un dépôt signé différent. Relancez-la avec --provenance required|optional pour changer la politique de provenance signée tout en préservant le dépôt, les approbateurs et les métadonnées du paquet. Exécutez emdash-plugin switch <did> lorsque le compte actif ne correspond pas à l’éditeur du manifeste. Pour les publications avec provenance, exécutez emdash-plugin release setup après avoir publié le profil.

`release setup`

release setup exécute la configuration du profil de paquet depuis un répertoire de plugin, puis crée un .github/workflows/emdash-release.yml partagé à la racine du dépôt Git. Les paquets de plugin imbriqués réutilisent le même workflow. Exécutez-le depuis un répertoire de plugin ou passez --dir <plugin-directory> ; la racine du dépôt n’identifie pas quel profil de paquet préparer.

emdash-plugin release setup

Elle accepte les flags de profile setup plus les options de workflow suivantes :

Flag	Default	Description
`--service-url <origin>`	`https://releases.emdashcms.com`	Origine HTTPS utilisée par l’Action générée.
`--action-ref <ref>`	`main`	Ref du dépôt EmDash contenant l’Action de release.
`--trigger <mode>`	`auto`	Source de publication : `changesets`, `tags` ou `manual`. `auto` propose Changesets lorsque `.changeset/config.json` existe.
`--force`	`false`	Remplacer un workflow généré existant. Sans cela, setup laisse le fichier existant inchangé.

Lorsque setup détecte Changesets dans un terminal interactif, il demande comment les plugins EmDash doivent être publiés. Follow Changesets releases publie les mêmes versions pour les paquets contenant emdash-plugin.jsonc. Les autres choix suivent les tags <slug>@<version> ou n’autorisent que des exécutions manuelles. En usage non interactif, auto sélectionne Changesets lorsqu’une configuration racine valide existe, sinon les tags de paquet.

La variante Changesets est un workflow réutilisable. Ajoutez un job appelant après le job de publication Changesets existant et passez sa sortie JSON officielle de paquets publiés. Les paquets privés uniquement EmDash exigent privatePackages.version: true et privatePackages.tag: true ; setup avertit lorsqu’une option manque.

La commande ne pousse jamais le workflow généré. La première exécution automatisée crée une demande de connexion au dépôt via GitHub OpenID Connect ; aucun secret Actions n’est requis. Suivez Automated plugin releases pour revoir le workflow, autoriser le service de release, connecter le dépôt et publier la première publication.

`release plan`

release plan est utilisé par le workflow généré. Avec --published-packages <json>, il mappe la sortie de l’Action Changesets vers les paquets contenant emdash-plugin.jsonc, vérifie leurs versions et écrit une matrice de sélecteurs JSON dans GITHUB_OUTPUT. Avec --package <slug[@version]>, il valide un sélecteur manuel. La commande ne construit ni ne publie de paquets.

`release prepare`

release prepare est le résolveur de paquets du workflow généré. Il trouve un manifeste de plugin dans le dépôt, vérifie une version de tag optionnelle, construit le paquet et écrit ses sorties de paquet, éditeur, répertoire et bundle dans GITHUB_OUTPUT.

Le workflow généré passe automatiquement un tag de paquet :

emdash-plugin release prepare gallery@1.2.3

Passez un ID de plugin simple pour une exécution manuelle du workflow. La commande utilise la version du manifeste de ce paquet. Les ID de plugin en double, les paquets manquants et les décalages de version échouent avant la création de provenance.

API programmatique

Construisez ou bundlez un plugin depuis Node.js en important les fonctions programmatiques de la CLI :

import { buildPlugin, bundlePlugin } from "@emdash-cms/plugin-cli";

await buildPlugin({ dir: "./my-plugin" });
const result = await bundlePlugin({ dir: "./my-plugin" });

Pour les aides de découverte et d’identifiants, importez depuis @emdash-cms/registry-client.