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 がプロファイルをブートストラップし、リリースサービスが create-only のリリースおよび blob 権限を保持します。

Atmosphere アカウント

公開は Atmosphere アカウント の下で行います。これは Bluesky やその他の AT Protocol ネットワークアプリで使われる、ユーザー所有のポータブルなアイデンティティです。アカウントはネットワーク上の唯一のログインで、どこでも同じ @handle を持ち、アイデンティティとデータは単一のアプリに縛られません。EmDash はこのアカウントをパブリッシャーアイデンティティとして使います。公開する各リリースは、あなたとして署名された、あなた自身のアカウント上のレコードです。

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 で選択肢を探せます。
  • セルフホスト。 自分のプロバイダーを運用し、アイデンティティとデータを完全に制御します。

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

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

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

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

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

正規の HTTPS リポジトリが利用可能な場合、コマンドはオプションの provenance 付きでパッケージプロファイルに追加します。リポジトリメタデータがないプロファイルでも、provenance なしのリリースは可能です。profile setup が provenance 必須にパッケージを設定した場合は、代わりに生成された 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、version、capabilities、hosts、およびソースコードから読み取った hooks と routes。手作業では維持しません。
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、ファイルごと ≤ 128 KB、≤ 20 ファイル。gzip tarball はその一部です。
  • backend.js に Node 組み込みなし — サンドボックスコードは fs、path、child_process などをインポートできません。Web API を使うか、そのロジックをネイティブプラグインに移します。
  • capabilities の健全性 — 名前は認識された集合に含まれている必要があります。
  • 信頼契約の整合性 — Capabilities と hosts のクロスルール 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": "./screenshots/editor.png" },
        { "file": "./screenshots/settings.jpg", "lang": "en" }
      ]
    }
  }
}

マニフェストで宣言されたリスティング画像は、tarball に含まれる慣例的な icon.png および screenshots/ ファイルとは別です。公開は宣言された各画像をパブリッシャーの PDS にアップロードし、その blob 参照をリリースレコードに書き込みます。各画像は 1 MiB、各辺 8,192 ピクセルが上限です。1 リリースで最大 8 枚のスクリーンショットを宣言できます。完全な形は リリースフィールド を参照してください。

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 は、同じ slug とバージョンの既存リリースの置き換えを拒否します。再公開前に version を上げてください。ビルドは package.json から version を読み取ります（バージョン値は 1 つに保つ を参照）。拡大した 信頼契約 には major、新しい hooks または routes には minor、修正には patch を上げます。

パブリッシャーの不一致

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

次に読むもの