La CLI emdash-plugin

@emdash-cms/plugin-cli è la toolchain di authoring: scaffold, build, watch, validate, bundle, publish, più identità e discovery. Il binario è emdash-plugin.

Comandi

La CLI fornisce i seguenti comandi:

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

I comandi di output non interattivi (whoami, validate, search, info, login, publish) accettano --json per output leggibile dalla macchina. I comandi di discovery (search, info) accettano --registry-url <url> (o EMDASH_REGISTRY_URL).

L’esempio seguente mostra i due script che la maggior parte dei plugin aggiunge a package.json:

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

init

Crea un nuovo plugin con init:

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

Questo crea un plugin autonomo: emdash-plugin.jsonc, src/plugin.ts (una route di esempio nella forma satisfies SandboxedPlugin), package.json, tsconfig.json, un test, un README e .gitignore. Uno slug è l’unico input richiesto. Uno scaffold creato solo da uno slug è un punto di partenza valido: il manifest contiene commenti TODO: per i pochi campi da compilare — publisher, autore e contatto di sicurezza — prima che il plugin venga caricato o pubblicato.

build

build legge emdash-plugin.jsonc, src/plugin.ts e un package.json fratello opzionale, ed emette i seguenti file:

dist/ è output di build. Non commitarlo. Il .gitignore dello scaffold lo esclude, e le installazioni lo ricostruiscono.

dev

Sorveglia src/**, emdash-plugin.jsonc e package.json, rimbalzando ricostruzioni a 150 ms. Le ricostruzioni sono serializzate. Su una ricostruzione fallita lascia l’ultimo buon dist/ in posizione, quindi un sito che importa il plugin tramite un link workspace/file continua a funzionare fino alla prossima build riuscita. Ctrl-C si chiude in modo pulito.

Sviluppa contro un sito reale eseguendo pnpm dev qui e pnpm add file:../path/to/this nel sito, quindi importa l’export predefinito del plugin in emdash({ sandboxed: [...] }).

validate

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

Controllo schema offline con diagnostica in stile tsc file:line:column, incluse le regole inter-campo del manifest. Nessuna rete. Buono come gate di pre-commit o CI. Vedi il riferimento del manifest.

bundle

bundle è un sottile passaggio di packaging su build:

--validate-only salta la creazione del tarball ma produce comunque gli artefatti dist/ — “validate” implica “build first”.

publish

La CLI non ospita artefatti; lo fai tu, ovunque pubblicamente.

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 legge il manifest per i campi del profilo e applica publisher pinning. Alla prima pubblicazione, passa --license e un contatto di sicurezza (o tienili nel manifest). I flag espliciti sovrascrivono i valori del manifest, il che è utile in CI; --no-manifest si esclude completamente.

Guida completa: Bundling e pubblicazione.

API programmatica

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

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

Per helper di discovery e credenziali, importa da @emdash-cms/registry-client.