Empacotar e publicar

Publique um plugin sandboxed funcional para que outros sites possam instalá-lo. A publicação é apenas para plugins sandboxed — os plugins nativos são distribuídos pelo npm.

Publique diretamente pela CLI ou use o serviço de releases automatizados para compilar e publicar a partir do GitHub Actions. Os dois caminhos gravam o release na sua conta Atmosphere. Você só precisa de um host de artefatos separado quando escolhe explicitamente o caminho --url da CLI direta.

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, para plugins que existem apenas no registro, no manifesto).
• Uma conta Atmosphere para publicar.

Escolher um método de publicação

Os dois métodos criam registros de pacote e de release pertencentes ao publisher. Escolha onde o build do release deve ser executado e qual credencial deve autorizá-lo.

Sua conta Atmosphere

Você publica com uma conta Atmosphere: uma identidade portátil e de propriedade do usuário, usada no Bluesky e em outros apps da rede AT Protocol. Uma conta é o seu único login em toda a rede, com o mesmo @handle em todo lugar, e sua identidade e seus dados não ficam presos a nenhum app específico. O EmDash usa essa conta como a sua identidade de publisher: cada release que você publica é um registro na sua própria conta, assinado como você.

O EmDash usa as mesmas contas Atmosphere para o login Atmosphere dos sites.

Usar uma conta existente

Se você já tem uma conta do Bluesky ou qualquer outra conta Atmosphere, entre com o handle dela:

emdash-plugin login alice.bsky.social

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

Criar uma conta

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

• Um app, como o Bluesky. Cadastrar-se no Bluesky cria uma conta Atmosphere hospedada pelo Bluesky. É o caminho mais rápido.
• Um provedor independente. Hosts de contas mantidos pela comunidade ou voltados à privacidade. Veja as opções em atmosphereaccount.com.
• Hospedagem própria. Execute o seu próprio provedor para ter controle total sobre a sua identidade e os seus dados.

Qualquer que seja a escolha, o @handle dessa conta é o que você passa para emdash-plugin login, e o DID da conta é o que você fixa como publisher no seu manifesto.

Publicar a partir do diretório do plugin

Faça login uma vez e depois publique a partir do diretório que contém emdash-plugin.jsonc:

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

publish executa as mesmas verificações de build e de validação que bundle, cria o arquivo gzip, envia-o para o seu servidor de dados pessoal (PDS), envia as imagens de listagem declaradas e grava o registro do release.

Quando há um repositório HTTPS canônico disponível, o comando o adiciona ao perfil do pacote com procedência opcional. Perfis sem metadados de repositório também permitem releases sem procedência. Se profile setup configurou o pacote para exigir procedência, publique pelo workflow do GitHub Actions gerado.

Bundle

bundle executa build, valida, coleta os 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]

Conteúdo do tarball

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.
• Nenhum módulo embutido do Node em backend.js — o código sandbox não pode importar fs, path, child_process etc. Use APIs Web ou mova essa lógica para um plugin nativo.
• Coerência das capabilities — os nomes precisam pertencer ao conjunto reconhecido.
• Coerência do contrato de confiança — as regras cruzadas de network:request / allowedHosts de Capabilities e hosts.
• Assets convencionais do bundle — um icon.png ou uma captura de tela ilegível é ignorado. A CLI avisa quando o ícone não tem 256×256 ou uma captura de tela excede 1920×1080, mas as dimensões sozinhas não fazem o bundle falhar. Cada arquivo incluído continua contando para os limites de número de arquivos e de tamanho descompactado.

Para inspecionar o tarball antes de publicar, liste o seu conteúdo:

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

Publish

Publique o código-fonte atual e hospede os seus artefatos no seu PDS:

emdash-plugin publish

O bloco de manifesto a seguir adiciona imagens de listagem. Os caminhos são relativos a emdash-plugin.jsonc; PNG, JPEG e WebP são suportados.

{
  "release": {
    "artifacts": {
      "icon": { "file": "./icon.png" },
      "banner": { "file": "./banner.webp" },
      "screenshots": [
        { "file": "./images/editor.png" },
        { "file": "./images/settings.jpg", "lang": "en" }
      ]
    }
  }
}

A publicação envia cada imagem declarada para o PDS do publisher e grava a sua referência de blob no registro do release. Cada imagem é limitada a 1 MiB e a 8.192 pixels em qualquer dimensão; um release pode declarar até oito capturas de tela. bundle também empacota no tarball o icon.png convencional e os arquivos PNG e JPEG de screenshots/, o manifesto os declare ou não, e cada arquivo empacotado conta para os limites de tamanho de 128 KB por arquivo e 256 KB no total. Guarde as capturas de tela declaradas em outra pasta, como images/. Veja Campos de release para o formato completo.

O que publish faz:

A CLI identifica o pacote publicado como @<publisher-handle>/<slug>, imprime a página pública que fica disponível após a aprovação e fornece um comando emdash-plugin info … --version <version> --watch. Esse comando lê diretamente as verificações atuais do labeler; os metadados de um pacote não aprovado continuam ausentes das respostas do agregador e do site público de plugins.

Se um login existente for anterior à publicação de blobs, publish informa MISSING_BLOB_SCOPE. Execute emdash-plugin logout e depois faça login novamente para aprovar os novos escopos.

Usar uma URL de pacote externa

Passe --url quando o bundle do pacote já estiver disponível por HTTPS ou o provedor da conta não aceitar blobs gzip:

emdash-plugin publish --url https://downloads.example.com/gallery-1.0.0.tar.gz

A CLI baixa a URL, valida o bundle servido e calcula o seu checksum. Nesse caminho, ela não envia o blob do pacote. As imagens de listagem continuam usando blobs do PDS.

Para comparar os bytes hospedados com um tarball local, adicione --local:

emdash-plugin publish \\
  --url https://downloads.example.com/gallery-1.0.0.tar.gz \\
  --local dist/gallery-1.0.0.tar.gz

As versões são imutáveis por padrão

emdash-plugin publish se recusa a substituir um release existente com o mesmo slug e a mesma versão. Aumente version antes de publicar novamente. O build lê version de package.json (veja Mantenha um único valor de versão). Aumente major quando o contrato de confiança for ampliado, minor para novos hooks ou rotas e patch para correções.

Incompatibilidade de publisher

Se publish falhar com MANIFEST_PUBLISHER_MISMATCH, a sessão ativa é uma conta Atmosphere diferente do publisher fixado no manifesto. Troque para a conta fixada com emdash-plugin switch <did> ou atualize publisher no manifesto se você realmente estiver 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
• Releases automatizados de plugins — publique a partir de um workflow aprovado do GitHub Actions
• O manifesto do plugin — campos, contrato de confiança, fixação do publisher
• Capabilities e segurança