マニフェスト

識別情報とバージョン

publisherとslugが、プラグインレジストリの中でパッケージを識別します。slugはプラグインのルートのURLにも使われるため、npmのパッケージ名とは別のものです。たとえば @example/plugin-gallery というパッケージには、gallery を使います。

バージョンの値を1つに保つ

ビルドは、version と package.json#version を突き合わせます。

• 両方のファイルでバージョンを指定している場合、値が一致している必要があります。
• 一方のファイルだけで指定している場合、ビルドはその値を使います。
• どちらのファイルでも指定していない場合、ビルドは失敗します。

npmパッケージの場合は、バージョンを package.json に書き、マニフェストからは省略します。package.json を持たない、プラグインレジストリ専用のプラグインでは、マニフェストに version を指定する必要があります。

パッケージのプロフィール

パッケージのプロフィールは、リリースをまたいで表示される、変わらない情報を提供します。

各セクションは、インラインの文字列か、マニフェストからの相対パスでのファイル参照で書きます。

"sections": {
	"description": "A longer description written in CommonMark.",
	"installation": { "file": "./docs/installation.md" },
	"security": { "file": "./SECURITY.md" },
}

解決後の各セクションは、20,000バイトかつ2,000書記素までです。ファイル参照はマニフェストのディレクトリの中にとどまる必要があります。絶対パスと、ディレクトリの外に出る .. のパスは拒否されます。

publish は、最初のリリースでパッケージのプロフィールを作成します。以降のリリースでは、プロフィールのフィールドは置き換えられません。公開済みのプロフィールは emdash-plugin update-package で編集します。このコマンドは、既定では変更内容をプレビューするだけで、--yes を付けたときだけ書き込みます。

信頼に関する取り決め

信頼に関する取り決め（trust contract）は、capabilities、allowedHosts、storage で構成されます。これらのフィールドは、プラグインが何にアクセスできるか、プラグインがどのコレクションを作成して所有するかを運営者に伝えます。

次の宣言は、コンテンツの読み取りを許可し、1つのAPIとそのサブドメインへのリクエストを許可し、ストレージのコレクションを1つ作成します。

"capabilities": ["content:read", "network:request"],
"allowedHosts": ["api.example.com", "*.cdn.example.com"],
"storage": {
	"events": {
		"indexes": ["savedAt", ["collection", "savedAt"]],
		"uniqueIndexes": ["eventId"],
	},
}

権限とホスト

3つのフィールドの既定値はすべて空です。雛形は、空の値を明示的に書き込みます。これによって、レビューする人が、プラグインが追加のアクセスもコレクションも求めていないことを確認できます。

network:request には、allowedHosts にホスト名だけの値が少なくとも1つ必要です。network:request:unrestricted は、意図的にすべての公開ホストを許可するため、空のリストが必要です。すべての権限（Capability）、その影響、ホストのパターン、実行時の強制については、権限（Capabilities）とセキュリティが正式なリファレンスです。

ストレージ

storage の各キーは、プラグインが所有するコレクションを1つ指定します。その indexes と uniqueIndexes によって、プラグインがどのフィールドで絞り込みや並べ替えをできるかが決まります。コレクション名、インデックスの設計、検索、ページ分割は、ストレージで説明しています。

インストール済みのサイトは以前の宣言に同意しているため、信頼に関する取り決めを少しでも変える場合は、プラグインの新しいバージョンが必要です。取り決めの範囲を広げる場合は、メジャーバージョンを上げます。

管理画面のページとウィジェット

サンドボックス型プラグインは、管理画面のページとダッシュボードのウィジェットをBlock Kitで描画します。マニフェストでは、それらを表示する場所を宣言します。

"admin": {
	"pages": [{ "path": "/settings", "label": "Settings", "icon": "settings" }],
	"widgets": [{ "id": "recent-events", "title": "Recent events", "size": "half" }],
}

ページのパスは / で始まり、英字、数字、/、_、- を使います。ウィジェットのIDには、プラグインのslugと同じ英小文字の識別子の文字を使います。ウィジェットのサイズは full、half、third のどれかです。

ページまたはウィジェットを宣言したプラグインは、src/plugin.ts に admin という名前のルートを定義する必要があります。このルートがないと、EmDashがBlock Kitのレスポンスのために呼び出す先がなくなるため、バンドルのチェックが失敗します。

リリース用のフィールド

release は、特定のバージョンについて記述します。トップレベルの repo のURLは、リリースの記録に書き込まれます。また、自動リリースの設定で、パッケージのプロフィールをGitHubのリポジトリに結び付けるためにも使われます。

env:emdash と env:astro で、そのリリースをインストールできるEmDashとAstroのバージョンの範囲を指定します。

"release": {
	"requires": {
		"env:emdash": ">=0.37.0",
		"env:astro": ">=5.0.0 <7.0.0",
	},
}

EmDashは、インストールの前にこれらの要件を確認します。無効な範囲を書くとマニフェストの検証が失敗し、互換性のないリリースはインストールされません。

成果物（artifacts）のファイルパスはマニフェストからの相対パスで、マニフェストのディレクトリの中にとどまる必要があります。PNG、JPEG、WebPに対応しています。各ファイルは1 MiBまで、縦横どちらも8,192ピクセルまでです。省略可能な lang プロパティには、BCP 47の言語タグで、ローカライズした画像の言語を指定します。公開時、これらのファイルはプラグインのバンドルとは別にアップロードされ、実測した形式、寸法、チェックサム、パーソナルデータサーバー（PDS）のblobの参照が記録されます。

公開者の固定

publisher は、誤って別のAtmosphereアカウントから公開してしまうことを防ぎます。アカウントのDIDを使います。

"publisher": "did:plc:abc123def456", // jane.example.com

公開や自動リリースの準備の前に、CLIはマニフェストのpublisherと、現在のセッションを比較します。ハンドルの場合は、比較のために現在のDIDに解決されます。一致しない場合は MANIFEST_PUBLISHER_MISMATCH で失敗します。これを無視するフラグはありません。

別のセッションが有効になっている場合は、emdash-plugin whoami を実行してから、固定したアカウントに切り替えます。

emdash-plugin switch did:plc:abc123def456

マニフェストのpublisherは、パッケージを別のアカウントに移管するときだけ変更します。

マニフェストを検証する

ビルドや公開の前に、マニフェストを検証します。

emdash-plugin validate

別のマニフェストを検証するには、ファイルまたはディレクトリを渡します。

emdash-plugin validate ./packages/plugin-gallery

検証はオフラインで動きます。重複したプロパティ、未知のフィールド、無効な値、同時に使えない形式、そして allowedHosts のリストが空なのに network:request を指定している場合のような、フィールドをまたぐエラーを報告します。

ビルドのコマンドはプラグインCLIを、リリースの流れはバンドルと公開を参照します。