Die emdash-plugin CLI

@emdash-cms/plugin-cli ist die Authoring-Toolchain: scaffold, build, watch, validate, bundle, publish, plus Identität und Discovery. Die Binärdatei ist emdash-plugin.

Befehle

Die CLI bietet folgende Befehle:

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

Die nicht-interaktiven Output-Befehle (whoami, validate, search, info, login, publish) akzeptieren --json für maschinenlesbare Ausgabe. Discovery-Befehle (search, info) akzeptieren --registry-url <url> (oder EMDASH_REGISTRY_URL).

Das folgende Beispiel zeigt die zwei 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:

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

Dies erstellt ein eigenständiges Plugin: emdash-plugin.jsonc, src/plugin.ts (eine Beispielroute in der satisfies SandboxedPlugin-Form), package.json, tsconfig.json, einen Test, eine README und .gitignore. Ein Slug ist die einzige erforderliche Eingabe. Ein Scaffold, das nur aus einem Slug erstellt wurde, ist ein gültiger Ausgangspunkt: Das Manifest enthält TODO:-Kommentare für die wenigen auszufüllenden Felder — Publisher, Autor und Sicherheitskontakt — bevor das Plugin geladen oder veröffentlicht wird.

build

build liest emdash-plugin.jsonc, src/plugin.ts und eine optionale benachbarte package.json und gibt folgende Dateien aus:

dist/ ist Build-Output. Committen Sie es nicht. Die .gitignore des Scaffolds schließt es aus, und Installationen bauen es neu.

dev

Überwacht src/**, emdash-plugin.jsonc und package.json und verzögert Rebuilds um 150 ms. Rebuilds werden serialisiert. Bei einem fehlgeschlagenen Rebuild bleibt das letzte funktionierende dist/ bestehen, sodass eine Site, die das Plugin über einen Workspace-/Datei-Link importiert, weiterhin funktioniert, bis der nächste erfolgreiche Build erfolgt. Ctrl-C beendet sauber.

Entwickeln Sie gegen eine echte Site, indem Sie hier pnpm dev ausführen und pnpm add file:../path/to/this in der Site, dann importieren Sie den Default-Export des Plugins in emdash({ sandboxed: [...] }).

validate

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 feldübergreifenden Regeln des Manifests. Kein Netzwerk. Gut als Pre-Commit- oder CI-Gate. Siehe die Manifest-Referenz.

bundle

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

--validate-only überspringt die Tarball-Erstellung, erzeugt aber dennoch die dist/-Artefakte — “validate” impliziert “build first”.

publish

Die CLI hostet keine Artefakte; Sie tun dies, überall öffentlich.

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 liest das Manifest für Profilfelder und erzwingt Publisher-Pinning. Bei der ersten Veröffentlichung übergeben Sie --license und einen Sicherheitskontakt (oder behalten Sie sie im Manifest). Explizite Flags überschreiben Manifest-Werte, was in CI nützlich ist; --no-manifest meldet sich vollständig ab.

Vollständige Anleitung: Bundling und Publishing.

Programmatische API

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-Helfer importieren Sie aus @emdash-cms/registry-client.