La CLI `emdash-plugin` | EmDash CMS Everything

@emdash-cms/plugin-cli genera, compila, valida y publica plugins aislados (sandboxed). También gestiona el inicio de sesión del publicador, perfiles de paquete, descubrimiento del registro y lanzamientos automatizados. El binario instalado es emdash-plugin.

La CLI usa una cuenta Atmosphere como identidad del publicador para perfiles de paquete y lanzamientos.

Instalar la CLI

Los plugins creados con pnpm dlx @emdash-cms/plugin-cli init ya incluyen la CLI como dependencia de desarrollo fijada. Añádala a un plugin existente antes de usar los demás comandos:

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

Los ejemplos usan pnpm exec emdash-plugin para que cada comando ejecute la versión instalada en el plugin. Use pnpm dlx para el comando init puntual, no para comandos repetidos de build, login o release.

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

Ejecute emdash-plugin <command> --help para los argumentos y flags actuales. Los comandos pensados para scripts, incluidos validate, publish, update-package, search, info, login y whoami, ofrecen salida JSON cuando su ayuda lista --json. Los comandos de descubrimiento aceptan --registry-url <url> o la variable de entorno EMDASH_REGISTRY_URL.

La salida legible identifica los paquetes del registro como @<publisher-handle>/<slug>. Un nombre de paquete npm se etiqueta npm package cuando los diagnósticos de build necesitan mostrarlo.

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

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

`init`

Cree un nuevo plugin con init:

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

Esto genera emdash-plugin.jsonc, src/plugin.ts, package.json, tsconfig.json, vitest.config.ts, una prueba respaldada por workerd, un README, AGENTS.md, un skill local creating-plugins y la configuración del gestor de paquetes. .agents/skills y .claude/skills enlazan al directorio canónico skills, y .claude/CLAUDE.md enlaza a AGENTS.md, para que Codex y Claude usen la misma guía del proyecto. El código fuente empieza con una ruta asignada a una constante tipada como SandboxedPlugin y exportada como predeterminada. La prueba invoca esa ruta a través del wrapper de sandbox de producción y el puente del host de EmDash.

La configuración interactiva pide el publicador, autor, contacto de seguridad y repositorio fuente, y muestra el resumen completo del proyecto antes de escribir. Los campos obligatorios no se pueden omitir.

La CLI detecta si npm, pnpm, Yarn o Bun la lanzó y genera comandos coincidentes. Anule la elección con --package-manager. Un scaffold de pnpm incluye la política de scripts de build revisada que necesita esbuild.

La configuración no interactiva exige metadatos de propiedad explícitos. Use la siguiente forma en scripts:

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

Pase --use-detected para optar por la sesión de publicador activa y los metadatos locales de autor o repositorio de Git. Sin ese flag, --yes no copia valores predeterminados locales que llevan identidad.

`build`

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

Artifact	What it is
`dist/plugin.mjs` (+ `dist/plugin.d.mts`)	Los hooks y rutas. Cargados en proceso (`plugins: []`) y por el cargador del sandbox (`sandboxed: []`).
`dist/manifest.json`	El manifiesto del plugin, incluidos los hooks y rutas leídos de `src/plugin.ts`. `bundle` incluye este archivo tal cual; los consumidores npm lo leen sin analizar el origen JSONC.
`dist/index.mjs` (+ `dist/index.d.mts`)	El módulo descriptor que un sitio importa en `astro.config.mjs`. Se emite solo cuando existe un `package.json` hermano; los plugins solo de registro lo omiten, porque nada lo importa.

dist/ es salida de build. No lo confirme en el repositorio. El .gitignore del scaffold lo excluye. Ejecute emdash-plugin build antes de empaquetar o publicar el paquete npm para que su lista files tenga los artefactos generados.

`dev`

Vigila src/**, emdash-plugin.jsonc y package.json, con debounce de rebuilds a 150 ms. Los rebuilds se serializan. En un rebuild fallido deja el último dist/ bueno en su sitio, de modo que un sitio que importa el plugin por un enlace workspace/file sigue funcionando hasta el siguiente build exitoso. Ctrl-C drenaje limpio.

Desarrolle contra un sitio real ejecutando pnpm dev en el directorio del plugin e instalándolo en el sitio con pnpm add file:../path/to/plugin. Importe la exportación predeterminada del plugin en emdash({ sandboxed: [...] }). El first-plugin tutorial muestra la configuración completa.

`validate`

Valide el manifiesto en el directorio actual, o pase un directorio de plugin distinto:

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

Comprobación de esquema sin conexión con diagnósticos al estilo tsc file:line:column, incluidas las reglas entre campos del manifiesto. Sin red. Bueno como puerta previa a commit o CI. Consulte the manifest reference.

`bundle`

bundle es un paso de empaquetado ligero sobre build:

Ejecuta build para producir dist/.
Valida el bundle: sin imports de builtins de Node, sin archivos demasiado grandes, sanity de capacidades.
Recoge assets opcionales — README, icono, capturas.
Crea un tarball. Dentro del tarball, plugin.mjs se empaqueta como backend.js (el nombre de archivo que espera el registro). La salida es dist/<slug>-<version>.tar.gz.

--validate-only omite la creación del tarball pero sigue produciendo los artefactos de dist/ — «validate» implica «build primero».

`publish`

publish compila y valida el plugin, sube el paquete y las imágenes del listado a su PDS, y escribe el registro de lanzamiento.

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

publish lee el manifiesto para campos de perfil y aplica publisher pinning. Mantenga la licencia, autor, contacto de seguridad y demás información del paquete en el manifiesto. Los flags de perfil antiguos y --no-manifest siguen disponibles para publicación con scripts legacy; consulte publish --help antes de mantener uno de esos flujos.

Pase --url <https-url> para usar un bundle de paquete alojado externamente. La CLI descarga y valida la URL antes de publicar. Añada --local <path> para verificar que un tarball local coincide con los bytes descargados.

Siga Bundling and publishing para el flujo completo de lanzamiento local.

`info`

info muestra los detalles del paquete aprobado desde el agregador. Tras publicar, pase la versión del lanzamiento y --watch para seguir las comprobaciones actuales de perfil y listado del lanzamiento:

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

Antes de la aprobación, el comando lee el estado directamente del labeler e imprime solo el identificador del paquete y el estado de comprobación. No devuelve metadatos de paquetes no aprobados desde el agregador. Una vez que el paquete y el lanzamiento son públicos, imprime los detalles aprobados y la URL canónica de la página del plugin. Deje de vigilar con Ctrl-C sin afectar los registros publicados ni las comprobaciones de listado.

Use --labeler-url <origin> o EMDASH_LABELER_URL al comprobar un registro que usa otro labeler.

`update-package`

Use update-package para cambiar un perfil de paquete existente sin crear un lanzamiento. Lee los campos de perfil en emdash-plugin.jsonc, obtiene el perfil firmado actual e imprime los cambios propuestos:

emdash-plugin update-package

El comando es un ensayo a menos que pase --yes:

emdash-plugin update-package --yes

La escritura usa el CID del registro actual como precondición. Si otro proceso cambia el perfil después de que el comando lo lea, la actualización falla con STALE_RECORD en lugar de sobrescribir el registro más nuevo. Quitar una propiedad opcional del manifiesto deja su valor publicado sin cambios; establezca el reemplazo previsto explícitamente.

`profile setup`

profile setup prepara el perfil de paquete del publicador para lanzamientos automatizados. Crea un perfil faltante desde emdash-plugin.jsonc, o añade ajustes de lanzamiento delegado a un perfil válido existente sin reemplazar sus metadatos de paquete.

Ejecute la configuración interactiva desde el directorio del plugin. Desde otro lugar en un monorepo, pase --dir <plugin-directory>:

emdash-plugin profile setup

Flag	Default	Description
`--dir <path>`	Directorio actual	Directorio fuente del plugin.
`--repository <url>`	`repo` del manifiesto, luego `origin` de Git	URL canónica del repositorio público de GitHub. La configuración interactiva rellena un remoto de GitHub detectado o pregunta cuando no hay ninguno.
`--provenance <mode>`	`required`	Use `required` para lanzamientos con provenance o `optional` para permitir lanzamientos locales sin provenance. La configuración interactiva pregunta.
`--confirmation <mode>`	`escalation-only`	Use `escalation-only` para aumentos de permiso o `always` para cada lanzamiento.
`--yes`, `-y`	`false`	Aceptar la política predeterminada sin preguntar. Obligatorio cuando una ejecución no interactiva cambiaría el perfil.

El comando usa el login activo de la CLI para escribir el perfil. Se niega a reemplazar un repositorio firmado distinto. Vuelva a ejecutarlo con --provenance required|optional para cambiar la política de provenance firmada conservando el repositorio, aprobadores y metadatos del paquete. Ejecute emdash-plugin switch <did> cuando la cuenta activa no coincida con el publicador del manifiesto. Para lanzamientos con provenance, ejecute emdash-plugin release setup tras publicar el perfil.

`release setup`

release setup ejecuta la configuración del perfil de paquete desde un directorio de plugin y luego crea un .github/workflows/emdash-release.yml compartido en la raíz del repositorio Git. Los paquetes de plugin anidados reutilizan el mismo workflow. Ejecútelo desde un directorio de plugin o pase --dir <plugin-directory>; la raíz del repositorio no identifica qué perfil de paquete preparar.

emdash-plugin release setup

Acepta los flags de profile setup más las siguientes opciones de workflow:

Flag	Default	Description
`--service-url <origin>`	`https://releases.emdashcms.com`	Origen HTTPS usado por la Action generada.
`--action-ref <ref>`	`main`	Ref del repositorio EmDash que contiene la Action de release.
`--trigger <mode>`	`auto`	Fuente del lanzamiento: `changesets`, `tags` o `manual`. `auto` ofrece Changesets cuando existe `.changeset/config.json`.
`--force`	`false`	Reemplazar un workflow generado existente. Sin él, setup deja el archivo existente sin cambios.

Cuando setup detecta Changesets en un terminal interactivo, pregunta cómo deben lanzarse los plugins EmDash. Follow Changesets releases publica las mismas versiones para paquetes que contienen emdash-plugin.jsonc. Las otras opciones siguen etiquetas <slug>@<version> o solo permiten ejecuciones manuales. En uso no interactivo, auto selecciona Changesets cuando existe una configuración raíz válida y etiquetas de paquete en caso contrario.

La variante Changesets es un workflow reutilizable. Añada un job llamador tras el job de publicación de Changesets existente y pase su salida JSON oficial de paquetes publicados. Los paquetes privados solo EmDash requieren privatePackages.version: true y privatePackages.tag: true; setup avisa cuando falta alguna opción.

El comando nunca hace push del workflow generado. La primera ejecución automatizada crea una solicitud de conexión del repositorio con GitHub OpenID Connect; no se requiere secreto de Actions. Siga Automated plugin releases para revisar el workflow, autorizar el servicio de release, conectar el repositorio y publicar el primer lanzamiento.

`release plan`

release plan lo usa el workflow generado. Con --published-packages <json>, mapea la salida de la Action Changesets a paquetes que contienen emdash-plugin.jsonc, verifica sus versiones y escribe una matriz de selectores JSON en GITHUB_OUTPUT. Con --package <slug[@version]>, valida un selector manual. El comando no compila ni publica paquetes.

`release prepare`

release prepare es el resolvedor de paquetes del workflow generado. Encuentra un manifiesto de plugin en el repositorio, comprueba una versión de etiqueta opcional, compila el paquete y escribe sus salidas de paquete, publicador, directorio y bundle en GITHUB_OUTPUT.

El workflow generado pasa una etiqueta de paquete automáticamente:

emdash-plugin release prepare gallery@1.2.3

Pase un ID de plugin simple para una ejecución manual del workflow. El comando usa la versión del manifiesto de ese paquete. IDs de plugin duplicados, paquetes faltantes y desajustes de versión fallan antes de crear provenance.

API programática

Compile o empaquete un plugin desde Node.js importando las funciones programáticas de la CLI:

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.