> English: [plugin-author-guide.md](./plugin-author-guide.md) # ampless プラグインの書き方 このガイドは、初めての `definePlugin()` 呼び出しから admin 編集可能な設定パネル、そして npm 公開に至るまで、ampless プラグインを ship するために必要な手順を一通りカバーします。Phase 1〜4 の機能を網羅 — descriptor ベースの `` / `` / 投稿単位 body 注入、非同期イベントフック、admin 管理の `settings.public` 値です。 設計の経緯と背景は [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md) に集約。本ページはその実装ハンドブック側です。 > **ポジショニング**: ampless はエンジニア向けのカスタマイズベース CMS です — プラグインは**サイトエンジニアが `cms.config.ts` でインポート + 設定する npm dep** です。エンジニアは他の npm ライブラリと同様にインストール前に各 dep を審査します（Astro integration / Next.js plugin パターン）。このガイドで説明する trust framework（`trust_level`、capabilities、IAM スコープ付き Lambda）は v1 において**ファーストパーティプラグインの code organization**として実装されています — どの trust 階層の Lambda が各イベントフックを実行するか、各階層が保有する IAM 権限、そして狭い範囲のポイントでのみ runtime hard gate を適用する（最も重要: `settings.secret` は `trust_level: 'trusted'` を要求、シークレット読み取りに trusted Lambda の IAM 権限が必要なため）。ほとんどの capability 宣言は runtime の hard gate ではなく soft warning + admin ラベル + 将来の allow-list surface です。任意の未審査サードパーティ untrusted プラグインを自動的に安全に動かすための marketplace-grade automatic sandbox としては**設計されていません**。マーケットプレイス + ランタイムサンドボックスは v2.0+ の探索であり、v1 の保証ではありません。詳細な trust model は [`docs/architecture/08-plugin-architecture.md#trust-model-v1-scope`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#trust-model-v1-scope) を参照してください。 --- ## 0. テーマとプラグインの境界線 ampless はテーマとプラグインの両方を提供します。用途に合ったものを選ぶことで、未来の自分や他のサイト作者が迷わずコードを見つけられます。 | やりたいこと | テーマを使う | プラグインを使う | |---|---|---| | レイアウト・タイポグラフィ・配色・ルート単位の UI | ✓ | | | home / post / tag ページのカスタムコンポーネント | ✓ | | | 非開発者が admin から編集できる設定 | | ✓ (`adminSettings`) | | コンテンツイベント後のバックグラウンド処理（RSS・検索インデックス・webhook） | | ✓ (`eventHooks`) | | 信頼できる副作用（S3 書き込み・外部 API 送信） | | ✓ (`writePublicAsset` + `trusted`) | | テーマに依存しない `` / `` 注入（アナリティクス・同意バナー） | | ✓ (`publicHead` / `publicBodyEnd`) | | 投稿単位の機械可読メタデータ（JSON-LD 等） | | ✓ (`schema` via `publicBodyForPost`) | | 投稿本文の周囲の可視 HTML（reading-time、breadcrumb、share など） | | ✓ (`publicHtmlForPost`) | | 複数の ampless サイトで共有したいコード | | ✓ (npm パッケージとして公開) | 判断の目安: - テーマ = **ページの見た目**。render 時は読み取り専用。 - プラグイン = **render を超えて起こること**: admin 編集可能な設定、バックグラウンド処理、テーマ非依存の注入、機械可読メタデータ、サイト間の再利用。 新しいプラグイン作者がよく踏む 2 つの境界線: - **ストレージ / DynamoDB / 外部 API 書き込みはプラグインに置く**。テーマは読み取り専用です。 - **admin が `/admin/plugins` からオン・オフしたい機能はプラグインに置く**。表面上の効果が純粋に見た目だけであっても同様です。テーマも独自の設定を持てますが、それはテーマ表示設定であり、サイト運用設定ではありません。 境界線上に本当に乗っている機能については [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md) で詳しく議論しています。 --- ## 1. プラグインで何ができるか ampless プラグインは 3 つのいずれかの場所に書きます — コードをどのくらい広く共有したいかに応じて選んでください: | どこに置くか | 使い時 | 置き場所 | |---|---|---| | **ファーストパーティ** | ampless コアへの全員向け貢献 | ampless モノレポ内の `packages/plugin-*/` | | **サイトローカル** | サイト固有のカスタマイズ、個別 publish 不要 | サイトリポジトリ内の `plugins//` | | **外部 npm パッケージ** | 他のサイトと共有したい、`npm publish` 想定 | スタンドアロンリポジトリ (`@scope/ampless-plugin-foo`) | 3 つの形式はすべて同じ `definePlugin({...})` ファクトリを呼び出し、同じサーフェスを使います。違いはパッケージング・配布方法、および静的 `package.json#amplessPlugin` マニフェストが有効にするインストール時バリデーションのオプトインです（§3 参照）。 §14 には一行のスキャフォールドコマンド (`npx create-ampless@beta plugin `) があり、後者 2 つのどちらにも即使えるボイラープレートを生成します。 ampless プラグインは `AmplessPlugin` オブジェクトを返す TypeScript モジュールです。以下のうち 1 つ以上のサーフェスにフックします: | サーフェス | 実行場所 | 同期 / 非同期 | Phase | |---|---|---|---| | `metadata(post, site)` | 投稿の `generateMetadata()` | 同期 | 既存 | | `siteMetadata(site)` | root layout の `generateMetadata()` | 同期 | 既存 | | `publicHead(ctx)` | root layout の `` | 同期 (async layout から呼ばれる) | 1 | | `publicBodyEnd(ctx)` | root layout の `` 末尾 | 同期 | 1 | | `publicBodyForPost(post, ctx)` | テーマの post ページテンプレート（投稿単位） | 同期 | 4 | | `publicHtmlForPost(post, ctx)` | テーマの post ページテンプレート（投稿単位、可視 HTML） | 同期 | 6d | | `ogImage` | `/og/[slug]` ルート | リクエスト時、公開 Lambda 内 | 既存 | | `hooks` | trust_level に応じた processor Lambda | 非同期、SQS イベントで起動 | 既存 | | `settings.public` | `/admin/plugins` フォーム | 宣言的なマニフェスト | 2 | 後続フェーズに残してある surface もいくつかあって、現状の `definePlugin` では形にできません: - **任意の `ReactNode` のページ注入**。同期描画 surface (`publicHead` / `publicBodyEnd` / `publicBodyForPost`) は descriptor 変種を返すだけ。 descriptor の validator は **runtime が描画する HTML 出力の安全境界** であって、プラグイン本体のコードを縛る JS sandbox ではない (プラグインは 普通の TypeScript としてサイトと同一の Node プロセス内で動く) - **同期描画 surface 内でのネットワーク**。これらの surface は宣言的な 出力を返す設計で、Promise を受け取らないし async result path も無い。 `publicHead` の中で `await fetch(...)` を書くと SSR が無期限ブロックする (デッドラインを返す手段がない)。外向き HTTP が必要な処理は trusted Lambda (`hooks`) でやる - **admin ルート / server ルート / コンテンツフィールドの追加** — Phase 6b 予約 - **Admin routes / server routes / content fields.** Phase 6b 予約。 `settings.public` に credential を置かないこと --- ## 2. 最小ファイル構成 プラグインを作る最速の方法はスキャフォールドです: ```bash # サイトローカル (現在の ampless サイトに plugins//index.ts を生成) npx create-ampless@beta plugin my-thing # スタンドアロン npm パッケージ (`npm publish` 向けの .// を生成) npx create-ampless@beta plugin @myscope/ampless-plugin-my-thing --standalone ``` 全体の手順は §14 を参照してください。このセクションの残りでは生成されるファイルの意味を説明します — 手書きしたい場合はここを読めば把握できます。 ### サイトローカル ``` plugins/ my-thing/ index.ts # ファクトリ関数のみ。これがプラグインの全体 ``` サイトの `package.json` / `tsconfig.json` がコンパイルを担うため、追加で ship するものはありません。`cms.config.ts` から相対 import で登録します。 ### スタンドアロン npm パッケージ ``` ampless-plugin-my-thing/ package.json tsconfig.json tsup.config.ts README.md CHANGELOG.md src/ index.ts index.test.ts ``` 本レポ内の `packages/plugin-rss/` と `packages/plugin-analytics-ga4/` が動作するファーストパーティの参考実装です — スタンドアロンスキャフォールドはこれらのレイアウトを踏襲します。 最小の `src/index.ts`: ```ts import { definePlugin, type AmplessPlugin } from 'ampless' export default function myPlugin(): AmplessPlugin { return definePlugin({ name: 'my-plugin', apiVersion: 1, trust_level: 'untrusted', capabilities: ['publicHead'], publicHead() { return [{ type: 'meta', name: 'x-plugin', content: 'hi' }] }, }) } ``` `cms.config.ts` に差し込み: ```ts import myPlugin from 'my-plugin' export default defineConfig({ site: { name: 'My Blog', url: 'https://example.com' }, plugins: [myPlugin()], }) ``` これで完了。`npm run dev` を再起動して任意のページのソースを表示すると `` が `` に出ています。 --- ## 3. `AmplessPlugin` マニフェスト ```ts interface AmplessPlugin { name: string // パッケージ風の識別子。例: 'analytics-ga4' packageName?: string // インストール時のクロスチェック用 npm パッケージ名 apiVersion: 1 // 現状唯一の有効値 trust_level: 'untrusted' | 'trusted' | 'privileged' instanceId?: string // 複数インストール時の namespace displayName?: LocalizedString // admin UI ラベル capabilities?: readonly PluginCapability[] hooks?: { ... } // 非同期イベント metadata?(post, site): PluginMetadata siteMetadata?(site): PluginMetadata publicHead?(ctx): readonly PublicHeadDescriptor[] publicBodyEnd?(ctx): readonly PublicBodyDescriptor[] publicBodyForPost?(post: Post, ctx): readonly PublicPostBodyDescriptor[] publicHtmlForPost?(post: Post, ctx): readonly PublicPostHtmlDescriptor[] tiptapNodeToMarkdown?: TiptapNodeMarkdownAdapters // server-safe markdown export adapters ogImage?: OgImageConfig settings?: { public?: readonly PluginSettingField[] secret?: readonly PluginSecretField[] version?: number // Phase 1 reservation; runtime ignores } } ``` ### `name` 短い識別子 (`'analytics-ga4'`、`'rss'`、`'webhook'` など)。デフォルトの `instanceId` および trusted processor が S3 に書き出す `public/plugins//` のプレフィックスに使われます。`/^[a-zA-Z0-9_-]+$/` 必須 — 「命名規則」セクション参照。 ### `apiVersion: 1` 今日は 1 のみ。将来の互換性破壊バージョンが出たらこの数字が bump され、runtime は未知の値を黙って bind せず拒否します。 **現状唯一の有効値は `apiVersion: 1` です。** literal type は他の値を compile-time に拒否し、`package.json#amplessPlugin.apiVersion` が `definePlugin()` の戻り値と異なる場合、または runtime の `SUPPORTED_API_VERSION` を超える場合、runtime は hard-throw します。 Phase 1 の compat-break reservation すべて（PR #220、#222、#230、#232、#234）は `apiVersion: 1` 内に収まります。これらをプラグインで declare するかどうかは契約バージョンに影響しません。 将来 `apiVersion: 2` が導入される場合は、changeset とこのガイドおよび architecture doc のセクション更新を通じてアナウンスされます。それまでは、**`apiVersion: 1` でプラグインを publish し、唯一の有効値として扱ってください**。v2 bump の trigger となるもの（ならないもの）の全基準については、architecture doc の [apiVersion bump policy](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#apiversion-bump-policy) セクションを参照してください。 ### `instanceId` optional、デフォルトは `name`。同じプラグインを 1 サイトで複数 instance 動かせる作り (例: 2 つの GA4 measurement ID、チャットプラットフォーム毎の webhook) では、ホストに `instanceId` を指定させて各々独立した namespace を持たせる: ```ts analyticsGa4Plugin({ instanceId: 'marketing' }) analyticsGa4Plugin({ instanceId: 'product' }) ``` `instanceId` も `name` も `/^[a-zA-Z0-9_-]+$/` を満たす必要があります。`.` は `pk='siteconfig', sk='plugins..'` の区切りを壊します。scope (`@foo/bar`) やスラッシュは予約済みです。 ### `displayName` `/admin/plugins` のパネル見出し。単一ロケールのプラグインなら平文の文字列で十分。`{ en: 'GA4', ja: 'GA4' }` 形式の per-locale map にすると admin のアクティブロケールに応じて読み分けられます。 ### `packageName` 省略可能。設定すると、runtime は起動時に `/package.json` を解決し、そこにある静的な `amplessPlugin` ブロックをファクトリの戻り値とクロスチェックします。これにより、runtime で初めて気づく（あるいは永遠に気づかない）インストール時のミスを検出できます — capability の不一致はクラッシュせず、該当サーフェスが静かにスキップされるだけです。 スタンドアロンプラグインでは、`package.json#name` で宣言している npm パッケージ名をここに設定します: ```ts return definePlugin({ name: 'site-verification', packageName: '@ishinao/ampless-plugin-site-verification', apiVersion: 1, // ... }) ``` サイトローカルプラグインは不要です — 未設定のままにするとクロスチェックはスキップされます（Phase 5 より前のプラグインとの後方互換）。 ### `package.json` の静的マニフェスト（スタンドアロンプラグインのみ） クロスチェックが静的マニフェストを見つけるには、公開パッケージに 2 つの条件が必要です: 1. `package.json#amplessPlugin` がファクトリの戻り値と同じフィールドを宣言している: ```json "amplessPlugin": { "apiVersion": 1, "name": "site-verification", "trustLevel": "untrusted", "capabilities": ["publicHead", "adminSettings"], "displayName": { "en": "Site verification", "ja": "サイト所有権確認" } } ``` 2. `package.json#exports` が `./package.json` を明示的に公開している: ```json "exports": { ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" }, "./package.json": "./package.json" } ``` これがないと、Node のパッケージエクスポートの制約により `import.meta.resolve('/package.json')` が `ERR_PACKAGE_PATH_NOT_EXPORTED` で拒否され、runtime はクロスチェックを静かにスキップします（プラグインは動きますが、インストール時ガードは機能しません）。 `create-ampless plugin --standalone` スキャフォールドは両方を正しく生成します。また `package.json#keywords` に `"ampless-plugin"` を加えておくことをお勧めします — npm 検索で ampless プラグインを探す際の慣例です。 runtime がチェックする内容: | フィールド | 不一致時の動作 | |---|---| | `apiVersion`（ファクトリ vs マニフェスト） | 起動時に **throws** | | `apiVersion`（runtime がサポートするバージョンより新しい） | 起動時に **throws** | | `name` | dev で warn | | `trustLevel` | dev で warn | | `capabilities`（集合比較） | dev で warn | 起動を中断するのは 2 つの `apiVersion` ケースのみです — これは runtime が対応していない ampless API でビルドされたプラグインのロードを防ぎます。その他はすべて開発者向けの警告であり、runtime のブロックではありません。 --- ## 4. `trust_level` の選び方 trust 階層は v1 において**ファーストパーティプラグインの code organization**として実装されています — イベントフックがどの IAM スコープ付き Lambda で実行されるか、その Lambda が保有する権限を決定します。これはエンジニアが審査した npm dep 向けの code organization surface であり、任意のサードパーティ未審査プラグインを自動的に安全に動かすための marketplace-grade automatic sandbox ではありません（上記の[ポジショニング注記](#ampless-プラグインの書き方)と[詳細な trust model](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#trust-model-v1-scope) を参照）。 3 階層、選択基準は **イベントフック (hooks) が何を必要とするか** で決まります (sync サーフェスは IAM に触れない): | 階層 | IAM | 今日動くもの | 用途 | |---|---|---|---| | `untrusted` | なし (SQS consume のみ) | 同期サーフェス + イベントフック | head/body descriptor、webhook 配送、コンテンツ変換 | | `trusted` | 投稿読み出し、`public/plugins//...` への書き込み | 同期サーフェス + イベントフック | RSS フィード、sitemap、計算済み JSON インデックス | | `privileged` | 予約（v2.0+ 探索のみ） | 同期サーフェスのみ — イベントフックはサイレントフィルタ（警告ログあり） | 将来のマーケットプレイス探索: SES、secret、private S3 | > **`privileged` プラグイン作者へ：** `trust_level: 'privileged'` とイベント > `hooks` を宣言した場合、**現時点でフックは実行されません**。両 processor が > privileged プラグインをフィルタアウトし、一致する SQS イベントごとに > `console.warn` を出力するため、サイレントドロップは可視化されます。 > 同期サーフェス（`publicHead`、`publicBodyEnd`、`metadata`、`publicBodyForPost`、 > `publicHtmlForPost`）は `trust_level` に関わらず正常に動き、警告も出ません。 > privileged Lambda プロビジョニングは v2.0+ の探索項目です — ampless が > プラグインマーケットプレイスを構築する場合、すでに `'privileged'` を宣言した > プラグインは自動的に新しい tier を使えるようになります。 > v1 ファーストパーティプラグインは trusted Lambda の現行 IAM スコープに収まる用途で `trust_level: 'trusted'` を使ってください。すなわち Post / KvStore / PluginSecret / PostTag の読み取り、`public/plugins/*` への S3 書き込み、外向き HTTP (AWS IAM 認証を必要としないもの) です。このスコープ外の要件 — SES、private S3 プレフィックス、自前の IAM プリンシパルを必要とする AWS API 呼び出し — は v2.0+ privileged Lambda 探索の対象で、v1 `trusted` には収まりません。 決め方の目安: - **`publicHead` / `publicBodyEnd` / `metadata` だけ必要** → `untrusted` - **hooks から投稿を読みたい (publish 時にフィードを再生成等)** → `trusted` - **`public/plugins/*` 以外への S3 PutObject や他の AWS API が必要** → 今はプラグインで ship せず、privileged 層を待つかプラグイン外で実装 trust level がズレているプラグインは「権限不足でサイレントに fail」または「不要に強い権限を持つ」のどちらか。階層を切り替えて再デプロイすれば直ります。 --- ## 5. 同期サーフェス **公開 Next.js プロセス** (サイト訪問者のリクエストスレッド) 内で同期実行 されます。これらの surface はネットワーク I/O を意図して設計していません。 async result path が無いので `publicHead` 内で `await fetch(...)` すると SSR がデッドラインなしでブロックします。ネットワーク呼び出しが必要な副作用 は `hooks` (trusted Lambda、async) でやってください。公開プロセス内の プラグインコードは公開ページ用の IAM ロールで動きます — 特別な AWS 権限は ありません。 | サーフェス | 戻り値 | 用途 | |---|---|---| | `metadata(post, site)` | `PluginMetadata` (Next.js `Metadata` 形) | 投稿単位の `