La CLI emdash-plugin | EmDash CMS Everything

@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:

Artefatto	Cos’è
`dist/plugin.mjs` (+ `dist/plugin.d.mts`)	Gli hook e le route. Caricato in-process (`plugins: []`) e dal caricatore sandbox (`sandboxed: []`).
`dist/manifest.json`	Il manifest del plugin, inclusi gli hook e le route letti da `src/plugin.ts`. `bundle` include questo file così com’è; i consumatori npm lo leggono senza analizzare la fonte JSONC.
`dist/index.mjs` (+ `dist/index.d.mts`)	Il modulo descrittore che un sito importa in `astro.config.mjs`. Emesso solo quando esiste un `package.json` fratello; i plugin solo registry lo saltano, poiché nulla lo importa.

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:

Esegue build per produrre dist/.
Valida il bundle: nessun import integrato Node, nessun file sovradimensionato, sanità delle capability.
Raccoglie asset opzionali — README, icona, screenshot.
Crea tarball. All’interno del tarball, plugin.mjs è impacchettato come backend.js (il nome file che il registry si aspetta). L’output è dist/<slug>-<version>.tar.gz.

--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.