Empacotar e publicar

Publique um plugin sandboxed funcional para que outros sites possam instalá-lo. Publicar é apenas sandboxed: plugins nativos são distribuídos via npm.

Publique diretamente pela CLI, ou use o serviço de releases automatizadas para construir e publicar a partir do GitHub Actions. Ambos os caminhos gravam o release na sua conta Atmosphere. Você só precisa de um host de artefatos separado quando escolhe explicitamente o caminho CLI direto --url.

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 no manifesto para plugins somente de registro).
• Uma conta Atmosphere sob a qual publicar.

Escolher um método de publicação

Ambos os métodos criam registros de pacote e release de propriedade do publisher. Escolha onde a build do release deve rodar e qual credencial deve autorizá-la.

Sua conta Atmosphere

Você publica sob uma conta Atmosphere: uma identidade portátil de propriedade do usuário usada no Bluesky e em outros apps da rede AT Protocol. Uma conta é seu único login na rede, com o mesmo @handle em todos os lugares, e sua identidade e dados não estão ligados a um único app. O EmDash usa essa conta como 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 do seu login Atmosphere para sites.

Usar uma conta existente

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

emdash-plugin login alice.bsky.social

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

Cadastrar-se para uma conta

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

• Um app, como o Bluesky. Inscrever-se no Bluesky cria uma conta Atmosphere hospedada pelo Bluesky. É o caminho mais rápido.
• Um provedor independente. Hosts de contas comunitários ou focados em privacidade. Explore opções em atmosphereaccount.com.
• Self-hosted. Execute seu próprio provedor para controle total sobre identidade e dados.

Qualquer que 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 manifesto.

Publicar a partir do diretório do plugin

Entre uma vez e então 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 validação que bundle, cria o arquivo gzip, faz upload para seu personal data server (PDS), envia quaisquer imagens de listagem declaradas e grava o registro de release.

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

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 os 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 gzip é uma fração disso.
• Sem built-ins 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.
• Sanidade de capabilities — os nomes devem estar no conjunto reconhecido.
• Consistência do contrato de confiança — as regras cruzadas network:request / allowedHosts de Capabilities e hosts.
• Assets convencionais do bundle — um icon.png ou captura ilegível é ignorado. A CLI avisa quando o ícone não é 256×256 ou uma captura excede 1920×1080, mas as dimensões sozinhas não fazem o bundle falhar. Cada arquivo incluído ainda conta para os limites de arquivos e tamanho descompactado.

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

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

Publish

Publique o código-fonte atual e hospede 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": "./screenshots/editor.png" },
        { "file": "./screenshots/settings.jpg", "lang": "en" }
      ]
    }
  }
}

As imagens de listagem declaradas no manifesto são distintas dos arquivos convencionais icon.png e screenshots/ incluídos no tarball. Publicar faz upload de cada imagem declarada para o PDS do publisher e grava sua referência de blob no registro de release. Cada imagem é limitada a 1 MiB e 8.192 pixels em qualquer dimensão; um release pode declarar até oito capturas. Veja Campos de release para a forma completa.

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ê as verificações atuais do labeler diretamente; metadados de pacotes não aprovados 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 entre novamente para aprovar os novos scopes.

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 seu checksum. Ela não faz upload do blob do pacote neste caminho. As imagens de listagem ainda usam 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

Versões são imutáveis por padrão

emdash-plugin publish recusa substituir um release existente com o mesmo slug e versão. Incremente version antes de republicar. A build lê version de package.json (veja Manter um único valor de versão). Incremente major para um contrato de confiança ampliado, minor para novos hooks ou rotas, e patch para correções.

Descompasso de publisher

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

O que ler a seguir

• A CLI emdash-plugin — cada comando
• Releases automatizadas de plugins — publicar a partir de um workflow aprovado do GitHub Actions
• O manifesto — campos, contrato de confiança, pinning do publisher
• Capabilities e segurança