A CLI emdash-plugin | EmDash CMS Everything

@emdash-cms/plugin-cli é a cadeia de ferramentas de autoria: scaffold, build, watch, validate, bundle, publish, mais identidade e descoberta. O binário é emdash-plugin.

Comandos

A CLI fornece os seguintes 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

Os comandos de saída não interativos (whoami, validate, search, info, login, publish) aceitam --json para saída legível por máquina. Os comandos de descoberta (search, info) aceitam --registry-url <url> (ou EMDASH_REGISTRY_URL).

O exemplo a seguir mostra os dois scripts que a maioria dos plugins adiciona ao package.json:

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

`init`

Crie um novo plugin com init:

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

Isso cria um plugin autônomo: emdash-plugin.jsonc, src/plugin.ts (uma rota de exemplo na forma satisfies SandboxedPlugin), package.json, tsconfig.json, um teste, um README e .gitignore. Um slug é a única entrada necessária. Um scaffold criado apenas a partir de um slug é um ponto de partida válido: o manifesto contém comentários TODO: para os poucos campos a preencher — editor, autor e contato de segurança — antes que o plugin seja carregado ou publicado.

`build`

build lê emdash-plugin.jsonc, src/plugin.ts e um package.json irmão opcional, e emite os seguintes arquivos:

Artefato	O que é
`dist/plugin.mjs` (+ `dist/plugin.d.mts`)	Os hooks e rotas. Carregado em processo (`plugins: []`) e pelo carregador sandbox (`sandboxed: []`).
`dist/manifest.json`	O manifesto do plugin, incluindo os hooks e rotas lidos de `src/plugin.ts`. `bundle` inclui este arquivo como está; consumidores npm o leem sem analisar a fonte JSONC.
`dist/index.mjs` (+ `dist/index.d.mts`)	O módulo descritor que um site importa em `astro.config.mjs`. Emitido apenas quando um `package.json` irmão existe; plugins somente de registro o ignoram, já que nada o importa.

dist/ é saída de compilação. Não faça commit dele. O .gitignore do scaffold o exclui, e as instalações o reconstroem.

`dev`

Observa src/**, emdash-plugin.jsonc e package.json, fazendo debounce de reconstruções em 150 ms. As reconstruções são serializadas. Em uma reconstrução falhada, deixa o último dist/ bom no lugar, para que um site importando o plugin via link de workspace/arquivo continue funcionando até a próxima compilação bem-sucedida. Ctrl-C fecha limpo.

Desenvolva contra um site real executando pnpm dev aqui e pnpm add file:../path/to/this no site, depois importe a exportação padrão do plugin para emdash({ sandboxed: [...] }).

`validate`

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

Verificação de esquema offline com diagnósticos estilo tsc file:line:column, incluindo as regras entre campos do manifesto. Sem rede. Bom como gate de pré-commit ou CI. Veja a referência do manifesto.

`bundle`

bundle é uma etapa fina de empacotamento sobre build:

Executa build para produzir dist/.
Valida o bundle: sem importações nativas do Node, sem arquivos superdimensionados, sanidade de capacidades.
Coleta ativos opcionais — README, ícone, capturas de tela.
Cria tarballs. Dentro do tarball, plugin.mjs é empacotado como backend.js (o nome do arquivo que o registro espera). A saída é dist/<slug>-<version>.tar.gz.

--validate-only pula a criação de tarball, mas ainda produz os artefatos dist/ — “validate” implica “build first”.

`publish`

A CLI não hospeda artefatos; você o faz, em qualquer 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 lê o manifesto para campos de perfil e impõe fixação de editor. Na primeira publicação, passe --license e um contato de segurança (ou mantenha-os no manifesto). Flags explícitas substituem valores do manifesto, o que é útil em CI; --no-manifest opta por sair completamente.

Passo a passo completo: Empacotamento e publicação.

API programática

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

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

Para auxiliares de descoberta e credenciais, importe de @emdash-cms/registry-client.