A CLI `emdash-plugin`

@emdash-cms/plugin-cli faz scaffold, build, validação e publicação de plugins sandboxed. Também gerencia login do publicador, perfis de pacote, descoberta do registro e lançamentos automatizados. O binário instalado é emdash-plugin.

A CLI usa uma conta Atmosphere como identidade do publicador para perfis de pacote e lançamentos.

Instalar a CLI

Plugins criados com pnpm dlx @emdash-cms/plugin-cli init já incluem a CLI como dependência de desenvolvimento fixada. Adicione-a a um plugin existente antes de usar os outros comandos:

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

Os exemplos usam pnpm exec emdash-plugin para que cada comando execute a versão instalada no plugin. Use pnpm dlx para o comando init pontual, não para comandos repetidos de build, login ou release.

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

Execute emdash-plugin <command> --help para os argumentos e flags atuais. Comandos destinados a scripts, incluindo validate, publish, update-package, search, info, login e whoami, fornecem saída JSON quando a ajuda lista --json. Comandos de descoberta aceitam --registry-url <url> ou a variável de ambiente EMDASH_REGISTRY_URL.

A saída legível identifica pacotes do registro como @<publisher-handle>/<slug>. Um nome de pacote npm é rotulado npm package quando diagnósticos de build precisam mostrá-lo.

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

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

init

Crie um novo plugin com init:

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

Isso faz scaffold de emdash-plugin.jsonc, src/plugin.ts, package.json, tsconfig.json, vitest.config.ts, um teste baseado em workerd, um README, AGENTS.md, um skill local creating-plugins e a configuração do gerenciador de pacotes. .agents/skills e .claude/skills apontam para o diretório canônico skills, e .claude/CLAUDE.md aponta para AGENTS.md, para que Codex e Claude usem a mesma orientação do projeto. O código começa com uma rota atribuída a uma constante tipada SandboxedPlugin e exportada como padrão. O teste invoca essa rota pelo wrapper de sandbox de produção e a ponte do host do EmDash.

A configuração interativa pede publicador, autor, contato de segurança e repositório fonte, e mostra o resumo completo do projeto antes de escrever. Campos obrigatórios não podem ser pulados.

A CLI detecta se npm, pnpm, Yarn ou Bun a iniciou e gera comandos correspondentes. Substitua a escolha com --package-manager. Um scaffold pnpm inclui a política de scripts de build revisada necessária ao esbuild.

A configuração não interativa exige metadados de propriedade explícitos. Use a forma a seguir em scripts:

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

Passe --use-detected para usar a sessão ativa do publicador e metadados locais de autor ou repositório Git. Sem esse flag, --yes não copia padrões locais que carregam identidade.

build

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

dist/ é saída de build. Não faça commit. O .gitignore do scaffold o exclui. Execute emdash-plugin build antes de empacotar ou publicar o pacote npm para que a lista files tenha os artefatos gerados.

dev

Observa src/**, emdash-plugin.jsonc e package.json, com debounce de rebuilds em 150 ms. Rebuilds são serializados. Em um rebuild falho, deixa o último dist/ bom no lugar, para que um site que importa o plugin via link workspace/file continue funcionando até o próximo build bem-sucedido. Ctrl-C encerra limpo.

Desenvolva contra um site real executando pnpm dev no diretório do plugin e instalando-o no site com pnpm add file:../path/to/plugin. Importe a exportação padrão do plugin em emdash({ sandboxed: [...] }). O first-plugin tutorial mostra a configuração completa.

validate

Valide o manifesto no diretório atual, ou passe um diretório de plugin diferente:

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

Verificação de schema offline com diagnósticos no estilo tsc file:line:column, incluindo as regras entre campos do manifesto. Sem rede. Bom como gate pre-commit ou CI. Veja the manifest reference.

bundle

bundle é um passo fino de empacotamento sobre build:

--validate-only pula a criação do tarball, mas ainda produz os artefatos dist/ — «validate» implica «build primeiro».

publish

publish faz build e valida o plugin, envia o pacote e as imagens do listing ao seu PDS, e escreve o registro de lançamento.

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

publish lê o manifesto para campos de perfil e aplica publisher pinning. Mantenha licença, autor, contato de segurança e outras informações do pacote no manifesto. Flags de perfil mais antigas e --no-manifest permanecem disponíveis para publicação com scripts legacy; consulte publish --help antes de manter um desses fluxos.

Passe --url <https-url> para usar um bundle de pacote hospedado externamente. A CLI baixa e valida a URL antes de publicar. Adicione --local <path> para verificar que um tarball local corresponde aos bytes baixados.

Siga Bundling and publishing para o fluxo completo de lançamento local.

info

info mostra os detalhes do pacote aprovado do agregador. Após publicar, passe a versão do lançamento e --watch para acompanhar as verificações atuais de perfil e listing do lançamento:

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

Antes da aprovação, o comando lê o status diretamente do labeler e imprime apenas o identificador do pacote e o estado da verificação. Não retorna metadados de pacotes não aprovados do agregador. Quando o pacote e o lançamento forem públicos, imprime os detalhes aprovados e a URL canônica da página do plugin. Pare de observar com Ctrl-C sem afetar os registros publicados ou as verificações de listing.

Use --labeler-url <origin> ou EMDASH_LABELER_URL ao verificar um registro que usa outro labeler.

update-package

Use update-package para alterar um perfil de pacote existente sem criar um lançamento. Lê os campos de perfil em emdash-plugin.jsonc, busca o perfil assinado atual e imprime as alterações propostas:

emdash-plugin update-package

O comando é um dry run a menos que você passe --yes:

emdash-plugin update-package --yes

A escrita usa o CID do registro atual como pré-condição. Se outro processo alterar o perfil depois que o comando o leu, a atualização falha com STALE_RECORD em vez de sobrescrever o registro mais novo. Remover uma propriedade opcional do manifesto deixa seu valor publicado inalterado; defina a substituição pretendida explicitamente.

profile setup

profile setup prepara o perfil de pacote do publicador para lançamentos automatizados. Cria um perfil ausente a partir de emdash-plugin.jsonc, ou adiciona configurações de lançamento delegado a um perfil válido existente sem substituir seus metadados de pacote.

Execute a configuração interativa a partir do diretório do plugin. De outro lugar em um monorepo, passe --dir <plugin-directory>:

emdash-plugin profile setup

O comando usa o login ativo da CLI para escrever o perfil. Recusa-se a substituir um repositório assinado diferente. Execute de novo com --provenance required|optional para alterar a política de provenance assinada preservando repositório, aprovadores e metadados do pacote. Execute emdash-plugin switch <did> quando a conta ativa não corresponder ao publicador do manifesto. Para lançamentos com provenance, execute emdash-plugin release setup após publicar o perfil.

release setup

release setup executa a configuração do perfil de pacote a partir de um diretório de plugin e então cria um .github/workflows/emdash-release.yml compartilhado na raiz do repositório Git. Pacotes de plugin aninhados reutilizam o mesmo workflow. Execute a partir de um diretório de plugin ou passe --dir <plugin-directory>; a raiz do repositório não identifica qual perfil de pacote preparar.

emdash-plugin release setup

Aceita as flags de profile setup mais as seguintes opções de workflow:

Quando setup detecta Changesets em um terminal interativo, pergunta como os plugins EmDash devem ser lançados. Follow Changesets releases publica as mesmas versões para pacotes que contêm emdash-plugin.jsonc. As outras opções seguem tags <slug>@<version> ou permitem apenas execuções manuais. Em uso não interativo, auto seleciona Changesets quando existe uma configuração raiz válida e tags de pacote caso contrário.

A variante Changesets é um workflow reutilizável. Adicione um job chamador após o job de publicação Changesets existente e passe sua saída JSON oficial de pacotes publicados. Pacotes privados só EmDash exigem privatePackages.version: true e privatePackages.tag: true; setup avisa quando falta alguma opção.

O comando nunca faz push do workflow gerado. A primeira execução automatizada cria uma solicitação de conexão do repositório com GitHub OpenID Connect; nenhum segredo de Actions é necessário. Siga Automated plugin releases para revisar o workflow, autorizar o serviço de release, conectar o repositório e publicar o primeiro lançamento.

release plan

release plan é usado pelo workflow gerado. Com --published-packages <json>, mapeia a saída da Action Changesets para pacotes que contêm emdash-plugin.jsonc, verifica suas versões e escreve uma matriz de seletores JSON em GITHUB_OUTPUT. Com --package <slug[@version]>, valida um seletor manual. O comando não faz build nem publica pacotes.

release prepare

release prepare é o resolvedor de pacotes do workflow gerado. Encontra um manifesto de plugin no repositório, verifica uma versão de tag opcional, faz build do pacote e escreve suas saídas de pacote, publicador, diretório e bundle em GITHUB_OUTPUT.

O workflow gerado passa uma tag de pacote automaticamente:

emdash-plugin release prepare gallery@1.2.3

Passe um ID de plugin simples para uma execução manual do workflow. O comando usa a versão do manifesto desse pacote. IDs de plugin duplicados, pacotes ausentes e divergências de versão falham antes de a provenance ser criada.

API programática

Faça build ou bundle de um plugin a partir do Node.js importando as funções programáticas da CLI:

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

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

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