はじめてのサンドボックス型プラグイン

前提条件

次のものが必要です。

• Node.jsとpnpm
• サンドボックスランナーを設定したEmDashのサイト
• マニフェストのpublisherフィールドに使う、AtmosphereアカウントのハンドルまたはDID

プラグインの雛形を作る

プラグインのアクセスとストレージを定義する

emdash-plugin.jsonc には、プラグインの識別情報、レジストリの情報、信頼に関する取り決めが入っています。content:afterSave は保存されたコンテンツをプラグインに渡すため、content:read の権限（Capability）を追加します。また、フックが保存ごとの記録を検索できる形で残せるように、events というストレージのコレクションを宣言します。

次のマニフェストには、このチュートリアルで使うフィールドが入っています。publisher、author、securityの値は、作成ツールが生成したものをそのまま残します。

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

	"slug": "save-log",
	"publisher": "did:plc:abc123def456",

	"license": "MIT",
	"author": { "name": "Jane Doe", "url": "https://example.com" },
	"security": { "email": "security@example.com" },
	"description": "Records content-save events.",

	"capabilities": ["content:read"],
	"allowedHosts": [],
	"storage": {
		"events": { "indexes": ["savedAt"] },
	},
}

content:read の宣言は、フックが保存されたコンテンツを受け取ることをサイトの運営者に伝えます。また、このプラグイン形式をプロセス内で動かす場合には、この宣言が必要です。コレクションがない場合、ctx.storage.events にアクセスすると例外が発生します。残りのフィールドと検証ルールは、マニフェストのリファレンスで説明しています。

フックとルートを追加する

生成された src/plugin.ts を、次の実行時の定義に置き換えます。

import type { SandboxedPlugin } from "emdash/plugin";

const plugin: SandboxedPlugin = {
	hooks: {
		"content:afterSave": {
			handler: async (event, ctx) => {
				const savedAt = new Date().toISOString();
				const contentId = String(event.content.id);
				await ctx.storage.events.put(`${savedAt}:${contentId}`, {
					savedAt,
					collection: event.collection,
					contentId,
				});

				ctx.log.info("Content save recorded", {
					collection: event.collection,
					contentId,
				});
			},
		},
	},

	routes: {
		health: {
			public: true,
			handler: async (_routeCtx, ctx) => {
				return { ok: true, plugin: ctx.plugin.id };
			},
		},
	},
};

export default plugin;

src/plugin.ts は、定義を SandboxedPlugin 型の定数に代入し、既定のエクスポートとして書き出します。この型注釈によって、フックとルートの引数に型が付きます。バンドルにEmDashのランタイムを含めたり、パッケージマネージャーごとに異なる型宣言のパスを生成したりすることはありません。

フックのハンドラーは (event, ctx) を受け取ります。ルートのハンドラーは (routeCtx, ctx) を受け取ります。health ルートは公開（public）で読み取り専用のため、管理画面のセッションなしで確認できます。公開ルートはインターネットからアクセスできます。実際のデータや変更操作を公開する前に、APIルートで認証とブラウザのオリジンのルールを確認してください。

生成されたテストを更新する

雛形のテストは、元の hello ルートを、Worker Loaderのトランスポートホストを通じて呼び出します。これを health ルートのテストに置き換えます。

import { afterEach, describe, expect, it } from "vitest";

import { createPluginTestHost, type PluginTestHost } from "@emdash-cms/plugin-test";

let host: PluginTestHost | undefined;

afterEach(async () => {
	await host?.dispose();
	host = undefined;
});

describe("health route", () => {
	it("identifies the running plugin", async () => {
		host = await createPluginTestHost();
		const result = await host.invokeRoute("health");
		expect(result).toEqual({ ok: true, plugin: "save-log" });
	});
});

このテストはプラグインをビルドし、Worker Loaderと PluginBridge を通じてルートを呼び出します。フック、コンテンツのフィクスチャー、ストレージのアサーション、ローカルのworkerdでのテストの制限は、サンドボックス型プラグインのテストガイドで説明しています。

検証とビルド

生成されたテストを実行し、マニフェストを検証して、npm用の成果物をビルドします。

pnpm run validate
pnpm run typecheck
pnpm run test
pnpm run build

ビルドで次のファイルが作られます。

• dist/plugin.mjs：フックとルートのコードが入っています。
• dist/manifest.json：実行時のマニフェストと、検出されたフック名とルート名が入っています。
• dist/index.mjs：サイトがインポートする、既定のエクスポートのディスクリプターです。

dist/ は生成された出力です。プラグインのビルドで作り直されるため、雛形ではGitの管理対象から除外されています。

プラグインを登録する

ローカルのパッケージをEmDashのサイトにインストールします。次のコマンドはサイトのディレクトリで実行します。2つのプロジェクトが同じ階層にない場合は、相対パスを調整します。

pnpm add file:../save-log

生成された既定のエクスポートを astro.config.mjs でインポートし、sandboxed に追加します。

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import saveLog from "save-log";

export default defineConfig({
	integrations: [
		emdash({
			sandboxed: [saveLog],
			sandboxRunner: "@emdash-cms/sandbox-workerd/sandbox",
		}),
	],
});

この例では、Node.jsのworkerdランナーを使っています。サイトがCloudflare Workersやその他の対応する構成を使っている場合は、すでに設定されているランナーをそのまま使います。

プラグインを動かす

2つの開発用のプロセスを起動します。

1. プラグインのディレクトリで pnpm dev を実行します。ソースまたはマニフェストが変わると、CLIがプラグインをビルドし直します。
2. サイトのディレクトリで、サイトの開発用コマンドを実行します。

サイトで次のルートを開きます。

http://localhost:4321/_emdash/api/plugins/save-log/health

レスポンスには、標準のAPIのエンベロープと、プラグインが返した値が入っています。

{
	"success": true,
	"data": { "ok": true, "plugin": "save-log" },
}

EmDashの管理画面でエントリーを保存します。サイトのログに Content save recorded が出力され、フックがプラグインの events コレクションに1件書き込みます。

さらに作り込む

• フック：フックのイベント、権限、実行順、エラーを説明します。
• APIルート：入力の検証、権限、公開ルート、MCPとしての公開を説明します。
• Block Kit：ブラウザ用のJavaScriptを配布せずに、管理画面のページを追加します。
• 設定：サイトごとのプラグインの設定を保存します。
• ストレージ：インデックスを使った検索とページ分割を説明します。
• テスト：サンドボックスのトランスポートを直接使うテストと、ランタイムを使うホストアクションのテストを説明します。
• バンドルと公開：プラグインをプラグインレジストリに公開します。