バンドルと公開
このページで分かること
- 公開の前提（マニフェストの必須項目、バージョン、Atmosphereアカウント）と、CLIから公開する方法と自動リリースの違い
bundleが作るファイルと、サイズの上限などの検証内容publishの流れ、外部URLのパッケージを使う方法、同じバージョンを上書きしない決まり、公開者が一致しないときの対処
このページの目次
動作するサンドボックス型プラグインを公開して、ほかのサイトがインストールできるようにします。公開できるのはサンドボックス型だけです。ネイティブ型プラグインは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アカウントを使います。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とデータを完全に管理します。
どれを選んだ場合でも、そのアカウントの @handle を emdash-plugin login に渡し、そのアカウントのDIDをマニフェストのpublisherに固定します。
やさしい解説
EmDashのプラグインレジストリに公開できるのはサンドボックス型プラグインだけで、ネイティブ型はnpmで配布します。レジストリへの公開では、Atmosphereアカウントが公開者の身元になります。Blueskyのアカウントを持っていれば、それがそのままAtmosphereアカウントとして使えます。公開したリリースは、自分のアカウントのレコードとして書き込まれます。マニフェストの publisher にアカウントのDIDを書いておくと、ほかのアカウントからは公開できなくなります。
プラグインのディレクトリからの公開
一度ログインしてから、emdash-plugin.jsonc があるディレクトリで公開します。
emdash-plugin login alice.example.com
emdash-plugin publish
publish は、bundle と同じビルドと検証を実行し、gzipのアーカイブを作り、自分の個人データサーバー（PDS）にアップロードし、宣言された掲載用の画像があればアップロードして、リリースのレコードを書き込みます。
バンドル
bundle はbuildを実行し、検証し、アセットを集めて、tarballを作ります。tarballの中では、plugin.mjs が backend.js（レジストリが想定するファイル名）としてまとめられます。
このコマンドは、次のフラグを受け付けます。
emdash-plugin bundle [--dir <path>] [--out-dir|-o <path>] [--validate-only]
| フラグ | デフォルト | 説明 |
|---|---|---|
--dir |
カレントディレクトリ | プラグインのソースのディレクトリ。 |
--out-dir、-o |
dist |
tarballの出力先のディレクトリ。 |
--validate-only |
false |
tarballは作らないが、dist/ の成果物は作る。 |
tarballの中身
| ファイル | 必須 | 説明 |
|---|---|---|
manifest.json |
はい | 生成されるマニフェスト。ID、バージョン、権限、ホスト、ソースから読み取ったフックとルートを含む。手作業で管理する必要はない。 |
backend.js |
はい | ビルドされた、単体で動く実行時のファイル（dist/plugin.mjs）。 |
README.md |
いいえ | プラグインのドキュメント。 |
icon.png |
いいえ | 慣例に従ったバンドルのアイコン。読み込めるPNGである必要がある。256×256を推奨。 |
screenshots/ |
いいえ | .png、.jpg、.jpeg のファイルを8つまで。1920×1080以下を推奨。 |
検証
bundle（と --validate-only）は、次のことを確認します。
- サイズの上限（RFC 0001、展開後）： 合計256 KB以下、ファイルごとに128 KB以下、ファイル数20以下。gzipで圧縮したtarballは、その数分の1の大きさです。
backend.jsにNodeの組み込みモジュールがないこと：サンドボックスのコードはfs、path、child_processなどをインポートできません。Web APIを使うか、その処理をネイティブ型プラグインに移します。- 権限の妥当性：権限名は、認識されている一覧に含まれている必要があります。
- 信頼に関する取り決めの整合性：権限とホストにある、
network:requestとallowedHostsの相互の規則です。 - 慣例に従ったバンドルのアセット：読み込めない
icon.pngやスクリーンショットはスキップされます。アイコンが256×256でない場合や、スクリーンショットが1920×1080を超える場合、CLIは警告を表示しますが、大きさだけを理由にバンドルが失敗することはありません。含まれるファイルはすべて、ファイル数と展開後のサイズの上限に数えられます。
公開前にtarballを確認するには、中身を一覧表示します。
emdash-plugin bundle
tar tzf dist/my-plugin-1.1.0.tar.gz
公開
現在のソースを公開し、その成果物を自分の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 が実行する処理：
- プラグインをビルドし、展開後の上限を検証して、gzipのアーカイブを作ります。
- Atmosphereアカウントのセッションを再開し、公開者の固定を確認します。
- OAuthの許可に、パッケージと画像のblobのスコープが含まれていることを確認します。
- パッケージと宣言された画像をPDSにアップロードし、返されたblobのCIDを、アップロードしたバイト列と照合して検証します。
- 初回の公開ではパッケージのプロフィールを作り、変更できないリリースのレコードを書き込みます。
CLIは、公開したパッケージを @<publisher-handle>/<slug> として識別し、承認後に利用できるようになる公開ページを表示し、emdash-plugin info … --version <version> --watch コマンドを示します。このコマンドは、ラベラー（labeler）の現在のチェック結果を直接読み取ります。承認されていないパッケージのメタデータは、アグリゲーターの応答にも公開のプラグインサイトにも表示されません。
既存のログインが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 を更新します。セッションの管理については、既存のアカウントの利用を参照してください。