E EmDash CMS Everything Guides, use cases, plugins, templates
日本語

バンドルと公開

このページ

動作するサンドボックス化されたプラグインを公開して、他のサイトがインストールできるようにします。公開の対象はサンドボックス化されたプラグインのみで、ネイティブプラグインは npm 経由で配布します。

CLI から直接公開することも、自動リリースサービスを使って GitHub Actions でビルドと公開を行うこともできます。どちらの経路でも、リリースは Atmosphere アカウントに書き込まれます。別のアーティファクトホストが必要になるのは、直接 CLI の --url 経路を明示的に選んだ場合だけです。

前提条件

  • slug、publisher、license、作者（author または authors）、セキュリティ連絡先（security または securityContacts）を含む有効な emdash-plugin.jsonc。emdash-plugin validate を実行して確認します。
  • version（package.json 内、またはレジストリ専用のプラグインではマニフェスト内）。
  • 公開に使う Atmosphere アカウント。

公開方法の選択

どちらの方法でも、パブリッシャーが所有するパッケージレコードとリリースレコードが作成されます。リリースのビルドをどこで実行するか、どの認証情報で認可するかを選びます。

方法使うタイミングアカウントへのアクセス
emdash-plugin publish自分のコンピューターなど、信頼できる環境でビルドして公開する場合。ローカルの CLI セッションが、パッケージプロファイル、リリース、blob を書き込みます。
自動リリースGitHub Actions がバージョンタグや手動のワークフロー実行からリリースをビルドする場合。ローカルの CLI がプロファイルを準備します。リリースサービスが保持するのは、リリースと blob の作成のみを許可する権限です。

Atmosphere アカウント

公開には Atmosphere アカウント を使います。これは、Bluesky や AT Protocol ネットワーク上のその他のアプリで共通して使える、ポータブルでユーザーが所有する ID です。1 つのアカウントがネットワーク全体で唯一のログインとなり、どこでも同じ @handle を使えます。ID とデータが特定のアプリに縛られることもありません。EmDash はこのアカウントをパブリッシャーの ID として使います。公開するすべてのリリースは、あなた自身のアカウント内のレコードであり、あなたとして署名されます。

EmDash は、サイトの Atmosphere ログインにも同じ Atmosphere アカウントを使います。

既存のアカウントを使う

すでに Bluesky アカウントやその他の Atmosphere アカウントを持っている場合は、そのハンドルでサインインします。

emdash-plugin login alice.bsky.social

ブラウザーでアカウントプロバイダーのサインインページが開きます。EmDash がパスワードを目にすることはありません。emdash-plugin whoami は保存されているセッションを一覧表示し、emdash-plugin switch <did> はアクティブなセッションを切り替えます。

アカウントに登録する

まだ Atmosphere アカウントを持っていない場合は、いずれかのプロバイダーで作成してから emdash-plugin login <your-handle> を実行します。選択肢は次のとおりです。

  • Bluesky などのアプリ。 Bluesky に登録すると、Bluesky がホストする Atmosphere アカウントが作成されます。これが最も手早い方法です。
  • 独立したプロバイダー。 コミュニティが運営する、またはプライバシーを重視したアカウントホスト。選択肢は atmosphereaccount.com で確認できます。
  • セルフホスト。 自分でプロバイダーを運用して、ID とデータを完全に管理します。

どれを選んでも、emdash-plugin login に渡すのはそのアカウントの @handle で、マニフェストで publisher として固定するのはそのアカウントの DID です。

プラグインディレクトリから公開する

一度ログインしてから、emdash-plugin.jsonc を含むディレクトリで公開します。

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

publish は bundle と同じビルドおよび検証チェックを実行し、gzip アーカイブを作成して、個人データサーバー（PDS）にアップロードします。宣言されたリスティング画像もアップロードし、リリースレコードを書き込みます。

正規の HTTPS リポジトリが利用できる場合、このコマンドは任意のプロビナンス付きでそれをパッケージプロファイルに追加します。リポジトリのメタデータがないプロファイルでは、プロビナンスなしのリリースも許可されます。profile setup でパッケージにプロビナンスを必須とする設定をした場合は、代わりに生成された GitHub Actions ワークフローを通じて公開してください。

Bundle

bundle は build を実行し、検証し、アセットを集めて、tarball を作成します。tarball の中では、plugin.mjs が backend.js（レジストリが期待するファイル名）としてパックされます。

このコマンドは次のフラグを受け付けます。

emdash-plugin bundle [--dir <path>] [--out-dir|-o <path>] [--validate-only]
フラグデフォルト説明
--dirカレントディレクトリプラグインのソースディレクトリ。
--out-dir, -odisttarball の出力ディレクトリ。
--validate-onlyfalsetarball は作成しませんが、dist/ の成果物は引き続き生成します。

tarball の内容

ファイル必須説明
manifest.jsonはい生成されるマニフェスト。id、バージョン、capability、ホスト、およびソースから読み取られたフックとルートが含まれます。手作業で管理する必要はありません。
backend.jsはいビルドされた、自己完結型のランタイムファイル（dist/plugin.mjs）。
README.mdいいえプラグインのドキュメント。
icon.pngいいえ慣例的なバンドルアイコン。読み取り可能な PNG である必要があります。256×256 を推奨します。
screenshots/いいえ最大 8 個の .png、.jpg、.jpeg ファイル。1920×1080 以下を推奨します。

検証

bundle（および --validate-only）は次の項目をチェックします。

  • サイズ上限（RFC 0001、展開後）: 合計 ≤ 256 KB、1 ファイルあたり ≤ 128 KB、≤ 20 ファイル。gzip 圧縮された tarball は、その一部の大きさです。
  • backend.js に Node の組み込みモジュールがないこと: サンドボックスのコードは fs、path、child_process などをインポートできません。Web API を使うか、そのロジックをネイティブプラグインに移してください。
  • Capability の妥当性: 名前は認識されている集合に含まれている必要があります。
  • 信頼契約の整合性: Capability とホストにある network:request / allowedHosts の相互ルール。
  • 慣例的なバンドルアセット: 読み取れない icon.png やスクリーンショットはスキップされます。アイコンが 256×256 でない場合やスクリーンショットが 1920×1080 を超える場合、CLI は警告を出しますが、寸法だけでバンドルが失敗することはありません。含まれるすべてのファイルは、引き続きファイル数と展開後サイズの上限に算入されます。

公開前に tarball を確認するには、その内容を一覧表示します。

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

Publish

現在のソースを公開し、そのアーティファクトを PDS にホストします。

emdash-plugin publish

次のマニフェストのブロックは、リスティング画像を追加します。パスは emdash-plugin.jsonc からの相対パスで、PNG、JPEG、WebP がサポートされています。

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

公開時には、宣言された各画像がパブリッシャーの PDS にアップロードされ、その blob 参照がリリースレコードに書き込まれます。各画像は 1 MiB まで、どちらの辺も 8,192 ピクセルまでに制限されており、1 つのリリースで宣言できるスクリーンショットは最大 8 枚です。bundle は、マニフェストで宣言されているかどうかにかかわらず、慣例的な icon.png と screenshots/ 内の PNG および JPEG ファイルも tarball にパックし、パックされた各ファイルは 1 ファイルあたり 128 KB、合計 256 KB のサイズ上限に算入されます。宣言したスクリーンショットは、images/ など別のフォルダーに保存してください。完全な形式については、リリースフィールドを参照してください。

publish は次のことを行います。

  1. プラグインをビルドし、展開後の上限を検証して、gzip アーカイブを作成します。
  2. Atmosphere アカウントのセッションを再開し、パブリッシャーの固定を確認します。
  3. OAuth の許可に、パッケージと画像 blob のスコープが含まれていることを確認します。
  4. パッケージと宣言された画像を PDS にアップロードし、返された各 blob の CID をアップロードしたバイト列と照合します。
  5. 初回の公開時にパッケージプロファイルを作成し、不変のリリースレコードを書き込みます。

CLI は、公開されたパッケージを @<publisher-handle>/<slug> として識別し、承認後に利用できる公開ページを表示して、emdash-plugin info … --version <version> --watch コマンドを示します。このコマンドはラベラーの現在のチェック結果を直接読み取ります。承認されていないパッケージのメタデータは、アグリゲーターのレスポンスにも公開プラグインサイトにも現れません。

既存のログインが blob 公開に対応する前のものである場合、publish は MISSING_BLOB_SCOPE を報告します。emdash-plugin logout を実行してから、再度ログインして新しいスコープを承認してください。

外部パッケージ URL を使う

パッケージのバンドルがすでに HTTPS で利用できる場合や、アカウントプロバイダーが gzip の blob を受け付けない場合は、--url を渡します。

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

CLI はその URL をダウンロードし、配信されたバンドルを検証して、チェックサムを計算します。この経路では、パッケージの blob はアップロードされません。リスティング画像には引き続き PDS の blob が使われます。

ホストされているバイト列をローカルの tarball と比較するには、--local を追加します。

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

バージョンはデフォルトで不変

emdash-plugin publish は、同じスラッグとバージョンの既存のリリースを置き換えることを拒否します。再度公開する前に version を上げてください。ビルドは package.json から version を読み取ります（バージョンの値は 1 か所にを参照）。信頼契約を広げる場合はメジャー、新しいフックやルートを追加する場合はマイナー、修正にはパッチを上げます。

パブリッシャーの不一致

publish が MANIFEST_PUBLISHER_MISMATCH で失敗した場合、アクティブなセッションが、マニフェストで固定されている publisher とは別の Atmosphere アカウントになっています。emdash-plugin switch <did> で固定されたアカウントに切り替えるか、プラグインを本当に新しいアカウントに移管する場合はマニフェストの publisher を更新してください。セッションの管理については、既存のアカウントを使うを参照してください。

次に読むもの