La CLI emdash-plugin

@emdash-cms/plugin-cli est la chaîne d’outils de création : scaffold, build, watch, validate, bundle, publish, plus l’identité et la découverte. Le binaire est emdash-plugin.

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 --url <url>            Publish a release pointing at a hosted tarball
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

Les commandes de sortie non interactives (whoami, validate, search, info, login, publish) acceptent --json pour une sortie lisible par machine. Les commandes de découverte (search, info) acceptent --registry-url <url> (ou EMDASH_REGISTRY_URL).

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 :

npx @emdash-cms/plugin-cli init my-plugin

Cela crée un plugin autonome : emdash-plugin.jsonc, src/plugin.ts (une route d’exemple dans la forme satisfies SandboxedPlugin), package.json, tsconfig.json, un test, un README et .gitignore. Un slug est la seule entrée requise. Un scaffold créé uniquement à partir d’un slug est un point de départ valide : le manifeste contient des commentaires TODO: pour les quelques champs à remplir — éditeur, auteur et contact de sécurité — avant que le plugin ne se charge ou ne soit publié.

build

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

dist/ est la sortie de build. Ne la commitez pas. Le .gitignore du scaffold l’exclut, et les installations la reconstruisent.

dev

Surveille src/**, emdash-plugin.jsonc et package.json, en dé-rebondissant les reconstructions à 150 ms. Les reconstructions sont sérialisées. Lors d’une reconstruction échouée, elle laisse le dernier bon dist/ en place, de sorte qu’un site important le plugin via un lien workspace/fichier continue de fonctionner jusqu’à la prochaine construction réussie. Ctrl-C se ferme proprement.

Développez contre un vrai site en exécutant pnpm dev ici et pnpm add file:../path/to/this dans le site, puis importez l’export par défaut du plugin dans emdash({ sandboxed: [...] }).

validate

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

Vérification de schéma hors ligne avec des diagnostics de style tsc file:line:column, incluant les règles inter-champs du manifeste. Pas de réseau. Bon comme porte de pré-commit ou CI. Voir la référence du manifeste.

bundle

bundle est une étape d’empaquetage mince au-dessus de build :

--validate-only saute la création de tarball mais produit toujours les artefacts dist/ — “validate” implique “build first”.

publish

La CLI n’héberge pas d’artefacts ; vous le faites, n’importe où publiquement.

emdash-plugin login           # if not already logged in
emdash-plugin bundle          # produces dist/<slug>-<version>.tar.gz
# upload that tarball to a public URL, then:
emdash-plugin publish --url https://your-host/my-plugin-1.0.0.tar.gz

publish lit le manifeste pour les champs de profil et applique l’épinglage d’éditeur. Lors de la première publication, passez --license et un contact de sécurité (ou conservez-les dans le manifeste). Les indicateurs explicites remplacent les valeurs du manifeste, ce qui est utile en CI ; --no-manifest se désabonne entièrement.

Tutoriel complet : Empaquetage et publication.

API programmatique

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

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

Pour les aides à la découverte et aux informations d’identification, importez depuis @emdash-cms/registry-client.