バンドルと公開 | EmDash CMS Everything

サンドボックスプラグインが動作するようになったら、EmDash マーケットプレイスに公開することで、他のサイトが管理ダッシュボードからワンクリックでインストールできるようになります。公開フローはサンドボックス専用です。ネイティブプラグインは npm 経由で配布され、マーケットプレイスの tarball にバンドルされません。

前提条件

公開する前に、プラグインが以下を満たしていることを確認してください:

"." エクスポート(ディスクリプタ)と "./sandbox" エクスポート(ランタイムエントリ)の両方を持つ package.json がある。
ディスクリプタで format: "standard" を使用している。
一意の id と有効な semver version がある。
capabilities と allowedHosts をディスクリプタに正確に宣言している。

バンドル形式

公開されたプラグインは、以下を含む .tar.gz tarball として配布されます:

ファイル	必須	説明
`manifest.json`	はい	ディスクリプタとサンドボックスエントリから抽出されたプラグインメタデータ
`backend.js`	はい	バンドルされたサンドボックスコード(自己完結型 ES モジュール)
`admin.js`	いいえ	バンドルされた管理 UI コード(Block Kit インタラクションが JS を提供する場合のみ)
`README.md`	いいえ	プラグインドキュメント
`icon.png`	いいえ	プラグインアイコン(256×256 PNG)
`screenshots/`	いいえ	最大 5 枚のスクリーンショット(PNG/JPEG、最大 1920×1080)

manifest.json は自動的に生成されます。プラグイン ID、バージョン、capabilities、許可されたホスト、フック名、ルート名、管理設定が含まれますが、実行可能コードは含まれません。

バンドルの構築

cd packages/plugins/my-plugin
emdash plugin bundle

これは以下を実行します:

package.json を読み取ってエントリーポイントを見つける。
ディスクリプタエントリをビルドして、ID、バージョン、capabilities、管理設定を抽出する。
"./sandbox" エクスポートから backend.js をバンドルする — 最小化、ツリーシェイク、完全に自己完結型。
"./admin" エクスポートが存在する場合は admin.js をバンドルする。
アセット(README、アイコン、スクリーンショット)を収集する。
バンドルを検証する(サイズ制限、backend.js に Node.js 組み込みモジュールがないこと、capabilities チェック)。
{id}-{version}.tar.gz を dist/ に書き込む。

エントリーポイントの解決

bundle コマンドは package.json のエクスポートを通じてコードを見つけます:

{
	"exports": {
		".": { "import": "./dist/index.mjs" },
		"./sandbox": { "import": "./dist/sandbox-entry.mjs" },
		"./admin": { "import": "./dist/admin.mjs" }
	}
}

エクスポート	目的	ビルド方法
`"."`	ディスクリプタ — マニフェストを抽出するために使用	Externals: `emdash`, `@emdash-cms/*`
`"./sandbox"`	サンドボックスで実行されるランタイムコード(`hooks`、`routes`)	完全に自己完結型(externals なし)
`"./admin"`	管理 UI コンポーネント(提供する場合のみ)	完全に自己完結型

"./sandbox" がない場合、コマンドはフォールバックとして src/sandbox-entry.ts を探します。バンドラーは dist パスを自動的にソースにマップします — "." エクスポートが ./dist/index.mjs を指している場合、src/index.ts を見つけてビルドします。

オプション

emdash plugin bundle [--dir <path>] [--outDir <path>]

フラグ	デフォルト	説明
`--dir`	カレントディレクトリ	プラグインソースディレクトリ
`--outDir`, `-o`	`dist`	tarball の出力ディレクトリ

検証

bundle コマンドは以下をチェックします:

サイズ制限 — バンドル全体が 5 MB 未満である必要があります。
backend.js に Node.js 組み込みモジュールがないこと — サンドボックスコードは fs、path、child_process などをインポートできません。Web API に置き換えるか、ロジックをネイティブプラグインに移動してください。
Capability ホワイトリスト — 宣言された capabilities は既知のセットに含まれている必要があります(タイポは失敗します)。
非推奨の capability 名 はここで警告をトリガーし、公開時にハードエラーになります。
allowedHosts なしの network:request は警告をトリガーします(ホストが実行時にオペレーターによって設定される場合は network:request:unrestricted を検討するか、ホストを明示的にリストしてください)。
アイコンのサイズ — icon.png は 256×256 である必要があります(間違っている場合は警告しますが、それでも含めます)。
スクリーンショットの制限 — 最大 5 枚、最大 1920×1080。

公開

emdash plugin publish

これは dist/ 内の最新の .tar.gz を見つけてアップロードします。tarball を明示的に指定するか、公開前にビルドするには:

# 明示的な tarball パス
emdash plugin publish --tarball dist/my-plugin-1.0.0.tar.gz

# 最初にビルドしてから公開
emdash plugin publish --build

認証

初めて公開する際、CLI は GitHub 経由で認証します:

CLI はブラウザで GitHub のデバイス認証ページを開きます。
ターミナルに表示されたコードを入力します。
GitHub がアクセストークンを発行します。
CLI はそれをマーケットプレイス JWT に交換します(~/.config/emdash/auth.json に保存されます)。

トークンは 30 日間有効です。期限切れ後、次の公開時に再認証を求められます。

認証を個別に管理できます:

emdash plugin login    # 公開せずにログイン
emdash plugin logout   # 保存されたトークンをクリア

初回登録

プラグイン ID がまだマーケットプレイスに知られていない場合、emdash plugin publish は最初のバージョンをアップロードする前に自動的に登録します。

バージョン要件

公開される各バージョンは、前のバージョンより高い semver を持つ必要があります。既存のバージョンを上書きまたは再公開することはできません — 再度公開する前に、package.json とディスクリプタの両方でバージョンを上げてください。

セキュリティ監査

公開された各バージョンは、自動セキュリティ監査を通過します。監査は backend.js と admin.js を以下についてスキャンします:

データ流出パターン
設定を介した認証情報の収集
難読化されたコード
リソース乱用(暗号マイニングなど)
疑わしいネットワークアクティビティ

監査は pass、warn、または fail の判定を生成し、プラグインのマーケットプレイスリストに表示されます。マーケットプレイスの実施レベルによっては、fail 判定により公開が完全にブロックされる場合があります。

オプション

emdash plugin publish [--tarball <path>] [--build] [--dir <path>] [--registry <url>]

フラグ	デフォルト	説明
`--tarball`	`dist/` 内の最新の `.tar.gz`	明示的な tarball パス
`--build`	`false`	公開前に `emdash plugin bundle` を実行
`--dir`	カレントディレクトリ	プラグインディレクトリ(`--build` と併用)
`--registry`	`https://marketplace.emdashcms.com`	マーケットプレイス URL

完全なワークフロー

典型的な公開サイクル:

# 1. 変更を加える
# 2. src/index.ts と package.json でバージョンを上げる
# 3. バンドルして公開
emdash plugin publish --build

最初にバンドルを検査したい場合:

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