Die `emdash-plugin`-CLI | EmDash CMS Everything

@emdash-cms/plugin-cli stellt Scaffolding, Build, Validierung und Veröffentlichung für Sandbox-Plugins bereit. Sie verwaltet auch Publisher-Anmeldung, Paketprofile, Registry-Suche und automatisierte Releases. Die installierte Binary heißt emdash-plugin.

Die CLI nutzt ein Atmosphere-Konto als Publisher-Identität für Paketprofile und Releases.

Die CLI installieren

Plugins, die mit pnpm dlx @emdash-cms/plugin-cli init erstellt wurden, enthalten die CLI bereits als gepinnte Entwicklungsabhängigkeit. Fügen Sie sie einem bestehenden Plugin hinzu, bevor Sie die anderen Befehle nutzen:

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

Die Beispiele verwenden pnpm exec emdash-plugin, damit jeder Befehl die im Plugin installierte Version ausführt. Nutzen Sie pnpm dlx für den einmaligen init-Befehl, nicht für wiederholte Build-, Login- oder Release-Befehle.

Befehle

Die CLI stellt die folgenden Befehle bereit:

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

Führen Sie emdash-plugin <command> --help für die aktuellen Argumente und Flags aus. Befehle für Skripte, darunter validate, publish, update-package, search, info, login und whoami, liefern JSON-Ausgabe, wenn ihre Hilfe --json listet. Discovery-Befehle akzeptieren --registry-url <url> oder die Umgebungsvariable EMDASH_REGISTRY_URL.

Menschenlesbare Ausgabe identifiziert Registry-Pakete als @<publisher-handle>/<slug>. Ein npm-Paketname wird als npm package beschriftet, wenn Build-Diagnosen ihn anzeigen müssen.

Das folgende Beispiel zeigt die beiden Skripte, die die meisten Plugins zu package.json hinzufügen:

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

`init`

Erstellen Sie ein neues Plugin mit init:

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

Das scaffoldet emdash-plugin.jsonc, src/plugin.ts, package.json, tsconfig.json, vitest.config.ts, einen workerd-gestützten Test, eine README, AGENTS.md, einen lokalen creating-plugins-Skill und die Paketmanager-Konfiguration. .agents/skills und .claude/skills verlinken auf das kanonische skills-Verzeichnis, und .claude/CLAUDE.md verlinkt auf AGENTS.md, sodass Codex und Claude dieselbe Projektführung nutzen. Die Quelle beginnt mit einer Route, die einer SandboxedPlugin-typisierten Konstante zugewiesen und als Default exportiert wird. Der Test ruft diese Route über EmDashs Production-Sandbox-Wrapper und Host-Bridge auf.

Interaktives Setup fragt nach Publisher, Autor, Security-Kontakt und Quell-Repository und zeigt die vollständige Projektzusammenfassung vor dem Schreiben. Pflichtfelder können nicht übersprungen werden.

Die CLI erkennt, ob npm, pnpm, Yarn oder Bun sie gestartet hat, und erzeugt passende Befehle. Überschreiben Sie die Wahl mit --package-manager. Ein pnpm-Scaffold enthält die geprüfte Build-Skript-Policy, die esbuild braucht.

Nicht-interaktives Setup erfordert explizite Ownership-Metadaten. Nutzen Sie in Skripten die folgende Form:

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

Übergeben Sie --use-detected, um die aktive Publisher-Session und lokale Git-Autor- oder Repository-Metadaten zu übernehmen. Ohne dieses Flag kopiert --yes keine identitätstragenden lokalen Defaults.

`build`

build liest emdash-plugin.jsonc, src/plugin.ts und eine optionale geschwisterliche package.json und erzeugt die folgenden Dateien:

Artifact	What it is
`dist/plugin.mjs` (+ `dist/plugin.d.mts`)	Die Hooks und Routen. Geladen in-process (`plugins: []`) und vom Sandbox-Loader (`sandboxed: []`).
`dist/manifest.json`	Das Manifest des Plugins, einschließlich der aus `src/plugin.ts` gelesenen Hooks und Routen. `bundle` nimmt diese Datei unverändert auf; npm-Konsumenten lesen sie, ohne die JSONC-Quelle zu parsen.
`dist/index.mjs` (+ `dist/index.d.mts`)	Das Descriptor-Modul, das eine Site in `astro.config.mjs` importiert. Wird nur erzeugt, wenn eine geschwisterliche `package.json` existiert; nur-Registry-Plugins überspringen es, da nichts es importiert.

dist/ ist Build-Ausgabe. Committen Sie sie nicht. Das .gitignore des Scaffolds schließt sie aus. Führen Sie emdash-plugin build aus, bevor Sie das npm-Paket packen oder veröffentlichen, damit seine files-Liste die erzeugten Artefakte hat.

`dev`

Überwacht src/**, emdash-plugin.jsonc und package.json und entprellt Rebuilds bei 150 ms. Rebuilds werden serialisiert. Bei einem fehlgeschlagenen Rebuild lässt es das letzte gute dist/ stehen, sodass eine Site, die das Plugin über einen Workspace-/File-Link importiert, bis zum nächsten erfolgreichen Build weiterarbeitet. Ctrl-C beendet sauber.

Entwickeln Sie gegen eine echte Site, indem Sie pnpm dev im Plugin-Verzeichnis ausführen und es mit pnpm add file:../path/to/plugin in die Site installieren. Importieren Sie den Default-Export des Plugins in emdash({ sandboxed: [...] }). Das first-plugin tutorial zeigt das vollständige Setup.

`validate`

Validieren Sie das Manifest im aktuellen Verzeichnis oder übergeben Sie ein anderes Plugin-Verzeichnis:

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

Offline-Schema-Prüfung mit tsc-artigen file:line:column-Diagnosen, einschließlich der Cross-Field-Regeln des Manifests. Kein Netzwerk. Gut als Pre-Commit- oder CI-Gate. Siehe the manifest reference.

`bundle`

bundle ist ein dünner Packaging-Schritt auf build:

Führt build aus, um dist/ zu erzeugen.
Validiert das Bundle: keine Node-Builtin-Imports, keine zu großen Dateien, Capability-Sanity.
Sammelt optionale Assets — README, Icon, Screenshots.
Erstellt ein Tarball. Im Tarball wird plugin.mjs als backend.js gepackt (der Dateiname, den die Registry erwartet). Die Ausgabe ist dist/<slug>-<version>.tar.gz.

--validate-only überspringt die Tarball-Erstellung, erzeugt aber weiterhin die dist/-Artefakte — „validate“ impliziert „zuerst bauen“.

`publish`

publish baut und validiert das Plugin, lädt Paket und Listing-Bilder in Ihre PDS hoch und schreibt den Release-Record.

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

publish liest das Manifest für Profilfelder und erzwingt publisher pinning. Halten Sie Lizenz, Autor, Security-Kontakt und andere Paketinformationen im Manifest. Die älteren Profil-Flags und --no-manifest bleiben für Legacy-skriptiertes Publishing verfügbar; prüfen Sie publish --help, bevor Sie einen solchen Flow pflegen.

Übergeben Sie --url <https-url>, um ein extern gehostetes Paket-Bundle zu nutzen. Die CLI lädt die URL herunter und validiert sie vor dem Veröffentlichen. Fügen Sie --local <path> hinzu, um zu prüfen, dass ein lokales Tarball mit den heruntergeladenen Bytes übereinstimmt.

Folgen Sie Bundling and publishing für den vollständigen lokalen Release-Flow.

`info`

info zeigt die genehmigten Paketdetails vom Aggregator. Nach dem Veröffentlichen übergeben Sie die Release-Version und --watch, um die aktuellen Profil- und Release-Listing-Prüfungen zu verfolgen:

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

Vor der Genehmigung liest der Befehl den Status direkt vom Labeler und gibt nur Paketkennung und Prüfstatus aus. Er liefert keine nicht genehmigten Paketmetadaten vom Aggregator. Sobald Paket und Release öffentlich sind, gibt er die genehmigten Details und die kanonische Plugin-Seiten-URL aus. Beenden Sie das Watching mit Ctrl-C, ohne die veröffentlichten Records oder Listing-Prüfungen zu beeinflussen.

Nutzen Sie --labeler-url <origin> oder EMDASH_LABELER_URL, wenn Sie eine Registry mit anderem Labeler prüfen.

`update-package`

Nutzen Sie update-package, um ein bestehendes Paketprofil zu ändern, ohne ein Release zu erzeugen. Es liest die Profilfelder in emdash-plugin.jsonc, holt das aktuelle signierte Profil und gibt die vorgeschlagenen Änderungen aus:

emdash-plugin update-package

Der Befehl ist ein Dry-Run, sofern Sie nicht --yes übergeben:

emdash-plugin update-package --yes

Der Schreibvorgang nutzt die aktuelle Record-CID als Vorbedingung. Wenn ein anderer Prozess das Profil ändert, nachdem der Befehl es gelesen hat, schlägt das Update mit STALE_RECORD fehl, statt den neueren Record zu überschreiben. Das Entfernen einer optionalen Eigenschaft aus dem Manifest lässt ihren veröffentlichten Wert unverändert; setzen Sie den gewünschten Ersatz explizit.

`profile setup`

profile setup bereitet das publisher-eigene Paketprofil für automatisierte Releases vor. Es erstellt ein fehlendes Profil aus emdash-plugin.jsonc oder fügt einem bestehenden gültigen Profil Delegated-Release-Einstellungen hinzu, ohne seine Paketmetadaten zu ersetzen.

Führen Sie das interaktive Setup aus dem Plugin-Verzeichnis aus. Von anderswo in einem Monorepo übergeben Sie --dir <plugin-directory>:

emdash-plugin profile setup

Flag	Default	Description
`--dir <path>`	Aktuelles Verzeichnis	Plugin-Quellverzeichnis.
`--repository <url>`	Manifest-`repo`, dann Git-`origin`	Kanonische öffentliche GitHub-Repository-URL. Interaktives Setup füllt eine erkannte GitHub-Remote vor oder fragt, wenn keine verfügbar ist.
`--provenance <mode>`	`required`	`required` für Provenance-gestützte Releases oder `optional`, um lokale Releases ohne Provenance zuzulassen. Interaktives Setup fragt.
`--confirmation <mode>`	`escalation-only`	`escalation-only` für Berechtigungserhöhungen oder `always` für jedes Release.
`--yes`, `-y`	`false`	Die Standardrichtlinie ohne Nachfrage akzeptieren. Erforderlich, wenn ein nicht-interaktiver Lauf das Profil ändern würde.

Der Befehl nutzt den aktiven CLI-Login, um das Profil zu schreiben. Er weigert sich, ein anderes signiertes Repository zu ersetzen. Führen Sie ihn erneut mit --provenance required|optional aus, um die signierte Provenance-Richtlinie zu ändern und Repository, Approver und Paketmetadaten zu erhalten. Führen Sie emdash-plugin switch <did> aus, wenn das aktive Konto nicht mit dem Manifest-Publisher übereinstimmt. Für Provenance-gestützte Releases führen Sie nach dem Veröffentlichen des Profils emdash-plugin release setup aus.

`release setup`

release setup führt das Paketprofil-Setup aus einem Plugin-Verzeichnis aus und erstellt dann eine gemeinsame .github/workflows/emdash-release.yml am Git-Repository-Root. Verschachtelte Plugin-Pakete nutzen denselben Workflow. Führen Sie ihn aus einem Plugin-Verzeichnis aus oder übergeben Sie --dir <plugin-directory>; das Repository-Root identifiziert nicht, welches Paketprofil vorbereitet werden soll.

emdash-plugin release setup

Er akzeptiert die Flags von profile setup plus die folgenden Workflow-Optionen:

Flag	Default	Description
`--service-url <origin>`	`https://releases.emdashcms.com`	HTTPS-Origin, den die generierte Action nutzt.
`--action-ref <ref>`	`main`	EmDash-Repository-Ref mit der Release-Action.
`--trigger <mode>`	`auto`	Release-Quelle: `changesets`, `tags` oder `manual`. `auto` bietet Changesets an, wenn `.changeset/config.json` existiert.
`--force`	`false`	Einen bestehenden generierten Workflow ersetzen. Ohne lässt Setup die bestehende Datei unverändert.

Wenn Setup Changesets in einem interaktiven Terminal erkennt, fragt es, wie EmDash-Plugins veröffentlicht werden sollen. Follow Changesets releases veröffentlicht dieselben Versionen für Pakete, die emdash-plugin.jsonc enthalten. Die anderen Optionen folgen Tags <slug>@<version> oder erlauben nur manuelle Läufe. Bei nicht-interaktiver Nutzung wählt auto Changesets, wenn eine gültige Root-Konfiguration existiert, sonst Paket-Tags.

Die Changesets-Variante ist ein wiederverwendbarer Workflow. Fügen Sie einen Caller-Job nach dem bestehenden Changesets-Publish-Job hinzu und übergeben Sie dessen offizielle JSON-Ausgabe veröffentlichter Pakete. Private nur-EmDash-Pakete erfordern privatePackages.version: true und privatePackages.tag: true; Setup warnt, wenn eine der Optionen fehlt.

Der Befehl pusht den generierten Workflow nie. Der erste automatisierte Lauf erstellt eine Repository-Verbindungsanfrage über GitHub OpenID Connect; kein Actions-Secret ist erforderlich. Folgen Sie Automated plugin releases, um den Workflow zu prüfen, den Release-Service zu autorisieren, das Repository zu verbinden und das erste Release zu veröffentlichen.

`release plan`

release plan wird vom generierten Workflow genutzt. Mit --published-packages <json> mappt es die Changesets-Action-Ausgabe auf Pakete mit emdash-plugin.jsonc, prüft ihre Versionen und schreibt eine JSON-Selektor-Matrix nach GITHUB_OUTPUT. Mit --package <slug[@version]> validiert es einen manuellen Selektor. Der Befehl baut oder veröffentlicht keine Pakete.

`release prepare`

release prepare ist der Paket-Resolver des generierten Workflows. Er findet ein Plugin-Manifest im Repository, prüft optional eine Tag-Version, baut das Paket und schreibt seine Paket-, Publisher-, Verzeichnis- und Bundle-Ausgaben nach GITHUB_OUTPUT.

Der generierte Workflow übergibt automatisch einen Paket-Tag:

emdash-plugin release prepare gallery@1.2.3

Übergeben Sie eine einfache Plugin-ID für einen manuellen Workflow-Lauf. Der Befehl nutzt die Version aus dem Manifest dieses Pakets. Doppelte Plugin-IDs, fehlende Pakete und Versionsabweichungen scheitern, bevor Provenance erzeugt wird.

Programmatische API

Bauen oder bundeln Sie ein Plugin aus Node.js, indem Sie die programmatischen Funktionen der CLI importieren:

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

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

Für Discovery- und Credential-Helper importieren Sie aus @emdash-cms/registry-client.