La CLI `emdash-plugin` | EmDash CMS Everything

@emdash-cms/plugin-cli esegue scaffolding, build, validazione e pubblicazione di plugin sandboxed. Gestisce anche l’accesso del publisher, i profili di pacchetto, la scoperta del registry e i rilasci automatizzati. Il binario installato è emdash-plugin.

La CLI usa un account Atmosphere come identità del publisher per profili di pacchetto e rilasci.

Installare la CLI

I plugin creati con pnpm dlx @emdash-cms/plugin-cli init includono già la CLI come dipendenza di sviluppo fissata. Aggiungila a un plugin esistente prima di usare gli altri comandi:

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

Gli esempi usano pnpm exec emdash-plugin così ogni comando esegue la versione installata nel plugin. Usa pnpm dlx per il comando init una tantum, non per comandi ripetuti di build, login o release.

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

Esegui emdash-plugin <command> --help per gli argomenti e i flag attuali. I comandi destinati agli script, tra cui validate, publish, update-package, search, info, login e whoami, forniscono output JSON quando la loro help elenca --json. I comandi di discovery accettano --registry-url <url> o la variabile d’ambiente EMDASH_REGISTRY_URL.

L’output leggibile identifica i pacchetti del registry come @<publisher-handle>/<slug>. Un nome di pacchetto npm è etichettato npm package quando le diagnostiche di build devono mostrarlo.

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:

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

Questo genera emdash-plugin.jsonc, src/plugin.ts, package.json, tsconfig.json, vitest.config.ts, un test basato su workerd, un README, AGENTS.md, uno skill locale creating-plugins e la configurazione del package manager. .agents/skills e .claude/skills collegano alla directory canonica skills, e .claude/CLAUDE.md collega a AGENTS.md, così Codex e Claude usano la stessa guida di progetto. Il codice inizia con una route assegnata a una costante tipizzata SandboxedPlugin ed esportata come default. Il test invoca quella route tramite il wrapper sandbox di produzione e il bridge host di EmDash.

Il setup interattivo chiede publisher, autore, contatto di sicurezza e repository sorgente, poi mostra il riepilogo completo del progetto prima di scrivere. I campi obbligatori non possono essere saltati.

La CLI rileva se npm, pnpm, Yarn o Bun l’ha avviata e genera comandi corrispondenti. Sovrascrivi la scelta con --package-manager. Uno scaffold pnpm include la policy di script di build revisionata necessaria a esbuild.

Il setup non interattivo richiede metadati di ownership espliciti. Usa la forma seguente negli script:

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

Passa --use-detected per usare la sessione publisher attiva e i metadati locali di autore o repository Git. Senza quel flag, --yes non copia i default locali che portano identità.

`build`

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

Artifact	What it is
`dist/plugin.mjs` (+ `dist/plugin.d.mts`)	Gli hook e le route. Caricati in-process (`plugins: []`) e dal loader sandbox (`sandboxed: []`).
`dist/manifest.json`	Il manifesto del plugin, inclusi hook e route letti da `src/plugin.ts`. `bundle` include questo file così com’è; i consumatori npm lo leggono senza analizzare la sorgente 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` sibling; i plugin solo registry lo saltano, perché nulla lo importa.

dist/ è output di build. Non fare commit. Il .gitignore dello scaffold lo esclude. Esegui emdash-plugin build prima di impacchettare o pubblicare il pacchetto npm così la sua lista files ha gli artefatti generati.

`dev`

Osserva src/**, emdash-plugin.jsonc e package.json, con debounce dei rebuild a 150 ms. I rebuild sono serializzati. Su un rebuild fallito lascia l’ultimo buon dist/ al suo posto, così un sito che importa il plugin via link workspace/file continua a funzionare fino al prossimo build riuscito. Ctrl-C termina in modo pulito.

Sviluppa contro un sito reale eseguendo pnpm dev nella directory del plugin e installandolo nel sito con pnpm add file:../path/to/plugin. Importa l’export default del plugin in emdash({ sandboxed: [...] }). Il first-plugin tutorial mostra il setup completo.

`validate`

Valida il manifesto nella directory corrente, oppure passa una directory di plugin diversa:

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

Controllo dello schema offline con diagnostiche stile tsc file:line:column, comprese le regole cross-field del manifesto. Nessuna rete. Buono come gate pre-commit o CI. Vedi the manifest reference.

`bundle`

bundle è un passaggio di packaging sottile sopra build:

Esegue build per produrre dist/.
Valida il bundle: nessun import di builtin Node, nessun file troppo grande, sanity delle capability.
Raccoglie asset opzionali — README, icona, screenshot.
Crea un tarball. Nel tarball, plugin.mjs è impacchettato come backend.js (il nome file atteso dal registry). L’output è dist/<slug>-<version>.tar.gz.

--validate-only salta la creazione del tarball ma produce comunque gli artefatti dist/ — «validate» implica «build prima».

`publish`

publish costruisce e valida il plugin, carica il pacchetto e le immagini del listing sul tuo PDS, poi scrive il record di release.

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

publish legge il manifesto per i campi del profilo e applica il publisher pinning. Mantieni licenza, autore, contatto di sicurezza e altre informazioni del pacchetto nel manifesto. I flag di profilo più vecchi e --no-manifest restano disponibili per la pubblicazione con script legacy; controlla publish --help prima di mantenere uno di quei flussi.

Passa --url <https-url> per usare un bundle di pacchetto ospitato esternamente. La CLI scarica e valida l’URL prima di pubblicare. Aggiungi --local <path> per verificare che un tarball locale corrisponda ai byte scaricati.

Segui Bundling and publishing per il flusso di release locale completo.

`info`

info mostra i dettagli del pacchetto approvato dall’aggregatore. Dopo la pubblicazione, passa la versione di release e --watch per seguire i controlli attuali di profilo e listing della release:

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

Prima dell’approvazione, il comando legge lo stato direttamente dal labeler e stampa solo l’identificatore del pacchetto e lo stato del controllo. Non restituisce metadati di pacchetti non approvati dall’aggregatore. Una volta che pacchetto e release sono pubblici, stampa i dettagli approvati e l’URL canonico della pagina del plugin. Interrompi il watch con Ctrl-C senza influenzare i record pubblicati o i controlli di listing.

Usa --labeler-url <origin> o EMDASH_LABELER_URL quando controlli un registry che usa un labeler diverso.

`update-package`

Usa update-package per modificare un profilo di pacchetto esistente senza creare una release. Legge i campi del profilo in emdash-plugin.jsonc, recupera il profilo firmato corrente e stampa le modifiche proposte:

emdash-plugin update-package

Il comando è un dry run a meno che non passi --yes:

emdash-plugin update-package --yes

La scrittura usa il CID del record corrente come precondizione. Se un altro processo cambia il profilo dopo che il comando lo ha letto, l’aggiornamento fallisce con STALE_RECORD invece di sovrascrivere il record più recente. Rimuovere una proprietà opzionale dal manifesto lascia invariato il suo valore pubblicato; imposta esplicitamente la sostituzione prevista.

`profile setup`

profile setup prepara il profilo di pacchetto del publisher per i rilasci automatizzati. Crea un profilo mancante da emdash-plugin.jsonc, oppure aggiunge impostazioni di release delegate a un profilo valido esistente senza sostituire i suoi metadati di pacchetto.

Esegui il setup interattivo dalla directory del plugin. Da altrove in un monorepo, passa --dir <plugin-directory>:

emdash-plugin profile setup

Flag	Default	Description
`--dir <path>`	Directory corrente	Directory sorgente del plugin.
`--repository <url>`	`repo` del manifesto, poi `origin` Git	URL canonico del repository GitHub pubblico. Il setup interattivo precompila un remote GitHub rilevato o chiede quando non è disponibile.
`--provenance <mode>`	`required`	Usa `required` per release con provenance o `optional` per consentire release locali senza provenance. Il setup interattivo chiede.
`--confirmation <mode>`	`escalation-only`	Usa `escalation-only` per aumenti di permesso o `always` per ogni release.
`--yes`, `-y`	`false`	Accettare la policy predefinita senza chiedere. Obbligatorio quando un’esecuzione non interattiva cambierebbe il profilo.

Il comando usa il login CLI attivo per scrivere il profilo. Rifiuta di sostituire un repository firmato diverso. Rieseguilo con --provenance required|optional per cambiare la policy di provenance firmata conservando repository, approvatori e metadati del pacchetto. Esegui emdash-plugin switch <did> quando l’account attivo non corrisponde al publisher del manifesto. Per release con provenance, esegui emdash-plugin release setup dopo aver pubblicato il profilo.

`release setup`

release setup esegue il setup del profilo di pacchetto da una directory di plugin, poi crea un .github/workflows/emdash-release.yml condiviso alla root del repository Git. I pacchetti di plugin annidati riutilizzano lo stesso workflow. Eseguilo da una directory di plugin o passa --dir <plugin-directory>; la root del repository non identifica quale profilo di pacchetto preparare.

emdash-plugin release setup

Accetta i flag di profile setup più le seguenti opzioni di workflow:

Flag	Default	Description
`--service-url <origin>`	`https://releases.emdashcms.com`	Origine HTTPS usata dall’Action generata.
`--action-ref <ref>`	`main`	Ref del repository EmDash che contiene l’Action di release.
`--trigger <mode>`	`auto`	Origine della release: `changesets`, `tags` o `manual`. `auto` propone Changesets quando esiste `.changeset/config.json`.
`--force`	`false`	Sostituire un workflow generato esistente. Senza, setup lascia invariato il file esistente.

Quando setup rileva Changesets in un terminale interattivo, chiede come devono essere rilasciati i plugin EmDash. Follow Changesets releases pubblica le stesse versioni per i pacchetti che contengono emdash-plugin.jsonc. Le altre scelte seguono i tag <slug>@<version> o consentono solo esecuzioni manuali. In uso non interattivo, auto seleziona Changesets quando esiste una configurazione root valida, altrimenti i tag di pacchetto.

La variante Changesets è un workflow riusabile. Aggiungi un job chiamante dopo il job di pubblicazione Changesets esistente e passa il suo output JSON ufficiale dei pacchetti pubblicati. I pacchetti privati solo EmDash richiedono privatePackages.version: true e privatePackages.tag: true; setup avvisa quando manca un’opzione.

Il comando non esegue mai push del workflow generato. La prima esecuzione automatizzata crea una richiesta di connessione del repository con GitHub OpenID Connect; non è richiesto alcun secret di Actions. Segui Automated plugin releases per rivedere il workflow, autorizzare il servizio di release, connettere il repository e pubblicare la prima release.

`release plan`

release plan è usato dal workflow generato. Con --published-packages <json>, mappa l’output dell’Action Changesets ai pacchetti che contengono emdash-plugin.jsonc, verifica le loro versioni e scrive una matrice di selettori JSON in GITHUB_OUTPUT. Con --package <slug[@version]>, valida un selettore manuale. Il comando non costruisce né pubblica pacchetti.

`release prepare`

release prepare è il risolutore di pacchetti del workflow generato. Trova un manifesto di plugin nel repository, controlla una versione di tag opzionale, costruisce il pacchetto e scrive le sue uscite di pacchetto, publisher, directory e bundle in GITHUB_OUTPUT.

Il workflow generato passa automaticamente un tag di pacchetto:

emdash-plugin release prepare gallery@1.2.3

Passa un ID di plugin semplice per un’esecuzione manuale del workflow. Il comando usa la versione dal manifesto di quel pacchetto. ID di plugin duplicati, pacchetti mancanti e disallineamenti di versione falliscono prima che venga creata la provenance.

API programmatica

Costruisci o bundla un plugin da Node.js importando le funzioni programmatiche della CLI:

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.