La CLI de emdash-plugin

@emdash-cms/plugin-cli es la cadena de herramientas de creación: scaffold, build, watch, validate, bundle, publish, más identidad y descubrimiento. El binario es emdash-plugin.

Comandos

La CLI proporciona los siguientes comandos:

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

Los comandos de salida no interactivos (whoami, validate, search, info, login, publish) aceptan --json para salida legible por máquina. Los comandos de descubrimiento (search, info) aceptan --registry-url <url> (o EMDASH_REGISTRY_URL).

El siguiente ejemplo muestra los dos scripts que la mayoría de los plugins agregan a package.json:

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

init

Crea un nuevo plugin con init:

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

Esto crea un plugin autocontenido: emdash-plugin.jsonc, src/plugin.ts (una ruta de ejemplo en la forma satisfies SandboxedPlugin), package.json, tsconfig.json, una prueba, un README y .gitignore. Un slug es la única entrada requerida. Un scaffold creado solo a partir de un slug es un punto de partida válido: el manifiesto lleva comentarios TODO: para los pocos campos a completar — editor, autor y contacto de seguridad — antes de que el plugin se cargue o publique.

build

build lee emdash-plugin.jsonc, src/plugin.ts y un package.json hermano opcional, y emite los siguientes archivos:

dist/ es salida de compilación. No lo confirme. El .gitignore del scaffold lo excluye, y las instalaciones lo reconstruyen.

dev

Observa src/**, emdash-plugin.jsonc y package.json, rebotando reconstrucciones a 150 ms. Las reconstrucciones están serializadas. En una reconstrucción fallida deja el último dist/ bueno en su lugar, por lo que un sitio que importa el plugin a través de un enlace de workspace/archivo sigue funcionando hasta la próxima compilación exitosa. Ctrl-C se cierra limpiamente.

Desarrolle contra un sitio real ejecutando pnpm dev aquí y pnpm add file:../path/to/this en el sitio, luego importe la exportación predeterminada del plugin en emdash({ sandboxed: [...] }).

validate

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

Verificación de esquema sin conexión con diagnósticos estilo tsc file:line:column, incluidas las reglas de campo cruzado del manifiesto. Sin red. Bueno como puerta de pre-commit o CI. Consulte la referencia del manifiesto.

bundle

bundle es un paso de empaquetado delgado sobre build:

--validate-only omite la creación de tarball pero aún produce los artefactos dist/ — “validate” implica “build first”.

publish

La CLI no aloja artefactos; usted lo hace, en cualquier lugar público.

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 lee el manifiesto para campos de perfil y aplica publisher pinning. En la primera publicación, pase --license y un contacto de seguridad (o manténgalos en el manifiesto). Las banderas explícitas anulan los valores del manifiesto, lo cual es útil en CI; --no-manifest se excluye por completo.

Tutorial completo: Empaquetado y publicación.

API programática

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

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

Para ayudantes de descubrimiento y credenciales, importe desde @emdash-cms/registry-client.