Empacotamento e publicação | EmDash CMS Everything

Uma vez que seu plugin sandbox funcione, publique-o para que outros sites possam instalá-lo. A publicação é apenas para sandbox — plugins nativos são distribuídos via npm.

Quando você publica, a CLI registra o lançamento na sua própria conta Atmosphere. Você hospeda o tarball — como um asset de release do GitHub, R2, S3 ou qualquer URL pública — e o registro armazena um link para ele.

Pré-requisitos

Um emdash-plugin.jsonc válido com slug, publisher, license, um autor (author ou authors) e um contato de segurança (security ou securityContacts). Execute emdash-plugin validate para confirmar.
Uma version (em package.json, ou o manifest para plugins apenas de registro).
Uma conta Atmosphere para publicar.

Sua conta Atmosphere

Você publica sob uma conta Atmosphere: uma identidade portátil de propriedade do usuário usada em Bluesky e outros aplicativos na rede AT Protocol. Uma conta é seu único login em toda a rede, com o mesmo @handle em todos os lugares, e sua identidade e dados não estão vinculados a nenhum aplicativo. O EmDash usa esta conta como sua identidade de publicador: cada lançamento que você publica é um registro em sua própria conta, assinado como você.

O EmDash usa as mesmas contas Atmosphere que seu login Atmosphere para sites.

Usar uma conta existente

Se você já tem uma conta Bluesky ou qualquer outra conta Atmosphere, faça login com seu handle:

emdash-plugin login alice.bsky.social

Isso abre a página de login do seu provedor de conta no navegador. O EmDash nunca vê sua senha. emdash-plugin whoami lista suas sessões armazenadas; emdash-plugin switch <did> muda a ativa.

Cadastrar-se para uma conta

Se você ainda não tem uma conta Atmosphere, crie uma através de qualquer provedor e execute emdash-plugin login <your-handle>. Suas opções:

Um aplicativo, como Bluesky. Cadastrar-se no Bluesky cria uma conta Atmosphere hospedada pelo Bluesky. Este é o caminho mais rápido.
Um provedor independente. Hosts de contas gerenciados pela comunidade ou focados em privacidade. Navegue pelas opções em atmosphereaccount.com.
Auto-hospedado. Execute seu próprio provedor para controle total sobre sua identidade e dados.

Qualquer que você escolher, o @handle dessa conta é o que você passa para emdash-plugin login, e o DID da conta é o que você fixa como publisher em seu manifest.

Três etapas

Os seguintes comandos fazem login, constroem um tarball e publicam um lançamento que aponta para o tarball hospedado:

emdash-plugin login                     # se ainda não estiver logado
emdash-plugin bundle                    # produz dist/<slug>-<version>.tar.gz
# faça upload desse tarball para uma URL pública, então:
emdash-plugin publish --url https://your-host/<slug>-<version>.tar.gz

bundle imprime as próximas duas etapas quando termina, incluindo a invocação de --url, então você não precisa lembrar o formato.

Bundle

bundle executa build, valida, coleta assets e cria um tarball. Dentro do tarball, plugin.mjs é empacotado como backend.js (o nome de arquivo que o registro espera).

O comando aceita as seguintes flags:

emdash-plugin bundle [--dir <path>] [--out-dir|-o <path>] [--validate-only]

Flag	Padrão	Descrição
`--dir`	Diretório atual	Diretório fonte do plugin.
`--out-dir`, `-o`	`dist`	Diretório de saída para o tarball.
`--validate-only`	`false`	Pular o tarball, mas ainda produzir artefatos de `dist/`.

Conteúdo do tarball

Arquivo	Obrigatório	Descrição
`manifest.json`	Sim	Manifest gerado: id, version, capabilities, hosts e os hooks e routes lidos da sua fonte. Você não mantém isso manualmente.
`backend.js`	Sim	O arquivo de runtime construído e autocontido (`dist/plugin.mjs`).
`README.md`	Não	Documentação do plugin.
`icon.png`	Não	PNG 256×256.
`screenshots/`	Não	Até 5, máx 1920×1080.

Validação

bundle (e --validate-only) verificam:

Limites de tamanho (RFC 0001, descompactado): total ≤ 256 KB, por arquivo ≤ 128 KB, ≤ 20 arquivos. O tarball compactado com gzip é uma fração disso.
Sem built-ins do Node em backend.js — código sandbox não pode importar fs, path, child_process, etc. Use Web APIs, ou mova essa lógica para um plugin nativo.
Sanidade de capabilities — nomes devem estar no conjunto reconhecido.
Coerência do contrato de confiança — as regras cruzadas de network:request / allowedHosts do manifest.
Limites de assets — ícone 256×256, ≤ 5 capturas de tela em ≤ 1920×1080.

Para inspecionar o tarball antes da publicação, liste seu conteúdo:

emdash-plugin bundle
tar tzf dist/my-plugin-1.1.0.tar.gz

Publish

A publicação escreve o registro de lançamento. O tarball já deve estar hospedado em uma URL pública:

emdash-plugin publish --url <hosted-tarball-url>

--url é obrigatório: é onde os bytes do plugin estão, e o registro do registro aponta para ele. Para verificar se a URL hospedada serve exatamente os bytes que você construiu antes de escrever o registro, passe --local:

emdash-plugin publish --url https://your-host/foo-1.0.0.tar.gz --local dist/foo-1.0.0.tar.gz

O que publish faz:

Busca o tarball em --url (com proteções de URL e tamanho) e extrai o manifest desses bytes.
Retoma sua sessão de conta Atmosphere e verifica fixação de publicador — a sessão ativa deve corresponder ao publisher fixado do manifest, ou é recusada com MANIFEST_PUBLISHER_MISMATCH.
Cria o perfil do pacote a partir do manifest na primeira publicação (license, autor, contato de segurança). Em publicações posteriores, o perfil existente prevalece.
Publica os registros de perfil e lançamento em sua conta.

Na primeira publicação, você pode fornecer campos de perfil por flag (--license, --security-email, …) em vez do manifest; flags explícitas substituem valores do manifest, o que é útil em CI. --no-manifest opta por não usar o manifest inteiramente.

Versões são imutáveis

Uma versão publicada não pode ser sobrescrita ou republicada. Incremente version antes de publicar novamente. O build lê version de package.json (veja a referência do manifest). Incremente major para um contrato de confiança ampliado, minor para novos hooks ou routes, e patch para correções.

Incompatibilidade de publicador

Se publish falhar com MANIFEST_PUBLISHER_MISMATCH, a sessão ativa é uma conta Atmosphere diferente do publisher fixado do manifest. Mude para a conta fixada com emdash-plugin switch <did>, ou atualize publisher no manifest se você está genuinamente transferindo o plugin para uma nova conta. Veja Usar uma conta existente para gerenciar sessões.

O que ler a seguir

A CLI emdash-plugin — todos os comandos
O manifest — campos, contrato de confiança, fixação de publicador
Capabilities e segurança