プラグインマニフェスト

サンドボックス化されたすべてのプラグインには、ルートディレクトリに emdash-plugin.jsonc ファイルがあります。プラグインが npm パッケージでもある場合は、package.json と同じ場所に置きます。マニフェストは、プラグインを識別し、必要なアクセスとストレージを宣言し、レジストリのリスティングとリリースのための情報を提供します。プラグイン CLI は、検証、ビルド、バンドル、公開、自動リリースの準備の際にこれを読み取ります。

このファイルは JSON with Comments（JSONC）形式なので、コメントや末尾のカンマが使えます。emdash-plugin init が作成する $schema プロパティは残しておいてください。エディターは生成されたスキーマを補完に使い、完全なチェックは emdash-plugin validate が行います。

次の例には、すべてのフィールドグループが含まれています。

{
	"$schema": "./node_modules/@emdash-cms/plugin-cli/schemas/emdash-plugin.schema.json",

	"slug": "gallery",
	"publisher": "did:plc:abc123def456",

	"license": "MIT",
	"author": { "name": "Jane Doe", "url": "https://example.com" },
	"security": { "email": "[email protected]" },
	"name": "Gallery",
	"description": "Image galleries for EmDash content.",
	"keywords": ["gallery", "images"],
	"sections": {
		"installation": { "file": "./docs/installation.md" },
		"faq": { "file": "./docs/faq.md" },
	},

	"capabilities": ["content:read"],
	"allowedHosts": [],
	"storage": {
		"galleries": { "indexes": ["contentId"] },
	},

	"admin": {
		"pages": [{ "path": "/gallery", "label": "Gallery", "icon": "image" }],
	},

	"repo": "https://github.com/example/plugin-gallery",
	"release": {
		"requires": { "env:emdash": ">=0.37.0" },
		"artifacts": {
			"icon": { "file": "./images/icon.png" },
			"screenshots": [{ "file": "./images/editor.png", "lang": "en" }],
		},
	},
}

識別情報とバージョン

パブリッシャーとスラッグが、レジストリ内でパッケージを識別します。スラッグはプラグインのルート 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 を付けたときにのみ書き込みます。

信頼契約

信頼契約は、capabilities、allowedHosts、storage で構成されます。これらのフィールドは、プラグインが何にアクセスでき、どのプラグイン所有のコレクションを作成するかをオペレーターに伝えます。

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

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

Capability とホスト

この 3 つのフィールドは、いずれも既定では空です。スキャフォールドは空の値を明示的に書き出すため、レビュー担当者はそのプラグインが追加のアクセスやコレクションを要求していないことが分かります。

network:request には、allowedHosts に少なくとも 1 つのホスト名（ワイルドカードなし）が必要です。network:request:unrestricted は、あえて任意の公開ホストを許可するため、空のリストが必要です。Capability とセキュリティは、すべてのケイパビリティ、その影響、ホストパターン、ランタイムでの強制について、正式なリファレンスです。

ストレージ

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

信頼契約のどの部分を変更する場合も、新しいプラグインバージョンが必要です。インストール済みのサイトは、以前の宣言に同意しているためです。契約を広げる場合は、メジャーバージョンを使います。

管理ページとウィジェット

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

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

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

ページには group を設定して、折りたたみ可能なサイドバーのフォルダーに入れることもできます。照合では大文字と小文字が区別され、前後の空白は無視されます。サイドバーに表示されているコレクションのグループと一致するグループを指定すると、そのページはそのフォルダーに入ります。それ以外の同じグループを共有するページは、どのプラグインのものであっても、Plugins セクション内でそのラベルのフォルダーを構成します。

ページまたはウィジェットを宣言するプラグインは、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 はインストール前にこれらの要件を確認します。無効な範囲はマニフェストの検証に失敗し、互換性のないリリースはインストールされません。

アーティファクトのファイルパスはマニフェストからの相対パスで、そのディレクトリ内に収まっている必要があります。PNG、JPEG、WebP に対応しています。各ファイルは 1 MiB 以下、縦横どちらも 8,192 ピクセル以下に制限されます。任意の lang プロパティで、ローカライズされた画像を BCP 47 言語タグで識別できます。公開時には、これらのファイルはプラグインバンドルとは別にアップロードされ、計測された種類、寸法、チェックサム、パーソナルデータサーバー（PDS）の blob 参照が記録されます。

パブリッシャーの固定

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

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

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

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

emdash-plugin switch did:plc:abc123def456

マニフェストのパブリッシャーを変更するのは、パッケージを別のアカウントに移管するときだけにしてください。

マニフェストを検証する

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

emdash-plugin validate

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

emdash-plugin validate ./packages/plugin-gallery

検証はオフラインで行われます。重複したプロパティ、不明なフィールド、無効な値、同時に指定できない形式、network:request があるのに allowedHosts のリストが空であるといった複数フィールドにまたがるエラーを報告します。

ビルドコマンドについてはプラグイン CLI、リリースの流れについてはバンドルと公開に進んでください。