create-ampless 1.0.0-alpha.111 → 1.0.0-alpha.115

package/dist/templates/_shared/docs/plugin-author-guide.ja.md

@@ -279,11 +279,20 @@ runtime がチェックする内容:
 
 3 階層、選択基準は **イベントフック (hooks) が何を必要とするか** で決まります (sync サーフェスは IAM に触れない):
 
-| 階層 | IAM | 用途 |
-|---|---|---|
-| `untrusted` | なし (SQS consume のみ) | head/body descriptor、webhook 配送、コンテンツ変換 |
-| `trusted` | 投稿読み出し、`public/plugins/<instanceId ?? name>/...` への書き込み | RSS フィード、sitemap、計算済み JSON インデックス |
-| `privileged` | 予約 | 将来: SES、secret、private S3 |
+| 階層 | IAM | 今日動くもの | 用途 |
+|---|---|---|---|
+| `untrusted` | なし (SQS consume のみ) | 同期サーフェス + イベントフック | head/body descriptor、webhook 配送、コンテンツ変換 |
+| `trusted` | 投稿読み出し、`public/plugins/<instanceId ?? name>/...` への書き込み | 同期サーフェス + イベントフック | RSS フィード、sitemap、計算済み JSON インデックス |
+| `privileged` | 予約 | 同期サーフェスのみ — イベントフックはサイレントフィルタ（警告ログあり） | 将来: SES、secret、private S3 |
+
+> **`privileged` プラグイン作者へ：** `trust_level: 'privileged'` とイベント
+> `hooks` を宣言した場合、**現時点でフックは実行されません**。両 processor が
+> privileged プラグインをフィルタアウトし、一致する SQS イベントごとに
+> `console.warn` を出力するため、サイレントドロップは可視化されます。
+> 同期サーフェス（`publicHead`、`publicBodyEnd`、`metadata`、`publicBodyForPost`、
+> `publicHtmlForPost`）は `trust_level` に関わらず正常に動き、警告も出ません。
+> privileged Lambda が用意された際、`'privileged'` を宣言済みのプラグインは
+> 自動的に新しい tier を使えるようになります — コードの変更は不要です。
 
 決め方の目安:
 
@@ -291,7 +300,7 @@ runtime がチェックする内容:
 - **hooks から投稿を読みたい (publish 時にフィードを再生成等)** → `trusted`
 - **`public/plugins/*` 以外への S3 PutObject や他の AWS API が必要** → 今はプラグインで ship せず、privileged 層を待つかプラグイン外で実装
 
-trust level がズレているプラグインは「権限不足で sliently fail」または「不要に強い権限を持つ」のどちらか。階層を切り替えて再デプロイすれば直ります。
+trust level がズレているプラグインは「権限不足でサイレントに fail」または「不要に強い権限を持つ」のどちらか。階層を切り替えて再デプロイすれば直ります。
 
 ---
 
@@ -964,6 +973,67 @@ admin は再デプロイなしにいつでも secret をローテーションで
 
 ---
 
+## 9b. プラグインのデータの保存場所
+
+プラグインが所有するデータは以下の 5 つのストレージ領域に置かれる可能性があり、**現状の書き込み経路は領域ごとに異なります**。3 つのファミリに分かれます:
+
+- **KvStore** — admin/editor が AppSync 経由で書き込みます。プラグインの hook には KvStore write helper は提供されていません。
+- **PluginSecret + PluginSecretIndicator** — `plugin-secret-handler` Lambda が書き込みます。admin/editor が `setPluginSecret` / `clearPluginSecret` AppSync mutation を呼ぶと、handler Lambda が DDB に書く流れです。trusted processor は `ctx.secret<T>()` で `PluginSecret` を読み取りますが、どちらの secret テーブルにも書き込みません。
+- **S3 `public/plugins/{instanceId ?? name}/*`** — trusted Lambda の hook context (`ctx.writePublicAsset(...)`) から書き込みます。プラグインの hook が直接書き込めるのはこの領域だけです。
+
+それ以外 — `Post`、`Page`、`Media`、`PostTag` DynamoDB テーブル、`public/site-settings.json` S3 ミラー、他プラグインの namespace — への書き込みは禁止です。現状 runtime が強制しているわけではなく、信頼（および将来の IAM 強化）によって担保されます。
+
+| 領域 | パス / 識別子 | アクセスレベル | Phase |
+|---|---|---|---|
+| KvStore（admin 設定） | DynamoDB `pk='siteconfig'`、`sk='plugins.<instanceId>.<fieldKey>'` | admin/editor が AppSync 経由で書く（プラグインの hook context には KvStore write helper は現状提供されていない） | Phase 2 |
+| KvStore（runtime 状態/キャッシュ） | DynamoDB `pk='pluginstate:<plugin>:...'`（TTL 任意） | admin/editor が AppSync 経由で書く（プラグインの hook context には KvStore write helper は現状提供されていない） | 現行 |
+| PluginSecret | DynamoDB `PluginSecret` テーブル、`sk='plugins.<instanceId>.<fieldKey>'` | `trusted` 限定（IAM 専用 AppSync 認証） | Phase 6a |
+| PluginSecretIndicator | DynamoDB `PluginSecretIndicator` テーブル、`sk='plugins.<instanceId>.<fieldKey>'` | `trusted` + admin/editor（indicator 読み取り） | Phase 6a |
+| S3 プラグイン成果物 | `public/plugins/{instanceId ?? name}/*` | `trusted` 限定（`writePublicAsset`） | Phase 3 |
+
+**cleanup は自動ではありません。** `cms.config.ts` からプラグインを外しても、5 領域のデータは自動削除されません。将来の lifecycle-dispatch PR が `uninstall` フックの起動メカニズムを追加するまで（§9c 参照）、オペレータによる手動削除が必要です。
+
+**独自 DynamoDB テーブル。** プラグインが ampless スキーマ外に独自の DynamoDB テーブルを持つ場合、lifecycle 管理（アンインストール時の cleanup を含む）はプラグイン著者の責任です。ampless は外部テーブルを把握しておらず、将来の `uninstall` cleanup grant は上記 5 領域のみをカバーします。
+
+詳細な設計根拠と IAM grant 設計については [`docs/architecture/08-plugin-architecture.ja.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.ja.md#プラグインが所有するデータ領域) を参照してください。
+
+---
+
+## 9c. `uninstall` フック（Phase 1 予約）
+
+`AmplessPlugin.uninstall` は **Phase 1 型予約** です — 現在 runtime はこれを呼び出しません。hook 名とシグネチャをプラグインコードが出回る前に確定し、将来の lifecycle-dispatch PR が名前・形を変更せずに起動を配線できるようにするのが目的です。
+
+**Phase 1 スコープ**: hook 名とシグネチャのみ予約。`ctx` には cleanup helper (`deletePublicAsset` / `deletePluginSetting` / `deletePluginSecret`) がまだありません — 今日 `await ctx.deletePublicAsset(...)` と書くと TypeScript エラーです。これらの helper が lifecycle-dispatch PR で追加される際は `PluginUninstallContext` への追加（additive）であり、空のボディを宣言済みのプラグインへの破壊変更はありません。
+
+**今日の推奨宣言** — 空のボディ:
+
+```ts
+// 例: S3 成果物と secret を書く trusted plugin
+definePlugin({
+  name: 'my-trusted-plugin',
+  apiVersion: 1,
+  trust_level: 'trusted',
+  capabilities: ['eventHooks', 'writePublicAsset', 'secretSettings'],
+  hooks: { 'content.published': async (_evt, ctx) => { /* ... */ } },
+  uninstall: async (_ctx) => {
+    // Phase 1 予約: runtime は今日このフックを呼び出しません。
+    // また `ctx` には cleanup helper
+    // (`deletePublicAsset` / `deletePluginSetting` /
+    // `deletePluginSecret`) がまだありません。
+    // 空ボディを宣言しておくのが forward-compat の推奨形です —
+    // 将来 lifecycle-dispatch PR がリリースされたとき、helper が
+    // `PluginUninstallContext` に追加され、そこで cleanup ボディを
+    // 実装します。今日の空宣言を再パブリッシュしなくても呼び出し
+    // イベントは受け取れますが、実際の cleanup ボディを追加するには
+    // 再パブリッシュが必要です。
+  },
+})
+```
+
+**冪等性。** lifecycle-dispatch PR がリリースされると、`uninstall` フックは trusted Lambda の IAM コンテキストで実行されます。SQS 配送は at-least-once なので cleanup ボディが複数回実行される可能性があります。安全にリトライできるよう設計してください（S3 の `deleteObject` は冪等、DDB の conditional delete も key が消えていれば safe）。
+
+---
+
 ## 10. ウォークスルー: GA4 を Phase 1 から Phase 2 に移行する
 
 Phase 1 の GA4 プラグインは measurement ID を constructor 引数で受けていました。Phase 2 では後方互換のためにその引数を残しつつ、値は `ctx.setting()` 経由で読みます。

package/dist/templates/_shared/docs/plugin-author-guide.md

@@ -341,11 +341,22 @@ Three tiers, picked by what the plugin needs to do **inside
 event hooks** (the sync surfaces — metadata, head, body — don't
 touch IAM):
 
-| Tier | IAM | Used by |
-|---|---|---|
-| `untrusted` | none (SQS consume only) | head/body descriptors, webhook delivery, content transforms |
-| `trusted` | read posts, write `public/plugins/<instanceId ?? name>/...` | RSS feed, sitemap, computed JSON indexes |
-| `privileged` | reserved | future: SES, secrets, private S3 |
+| Tier | IAM | What runs today | Used by |
+|---|---|---|---|
+| `untrusted` | none (SQS consume only) | sync surfaces + event hooks | head/body descriptors, webhook delivery, content transforms |
+| `trusted` | read posts, write `public/plugins/<instanceId ?? name>/...` | sync surfaces + event hooks | RSS feed, sitemap, computed JSON indexes |
+| `privileged` | reserved | sync surfaces only — event hooks are silently filtered out (warning logged) | future: SES, secrets, private S3 |
+
+> **Warning for `privileged` plugin authors:** If you declare
+> `trust_level: 'privileged'` with event `hooks` today, **your hooks
+> WILL NOT EXECUTE**. Both event processors filter out privileged
+> plugins and emit a `console.warn` on every matching SQS event so
+> the drop is visible. Sync render surfaces (`publicHead`,
+> `publicBodyEnd`, `metadata`, `publicBodyForPost`, `publicHtmlForPost`)
+> work normally regardless of `trust_level` and emit no warning.
+> When the privileged Lambda provisioning PR lands, plugins that
+> already declared `'privileged'` will automatically pick up the new
+> tier — nothing needs to change in your code.
 
 Rule of thumb:
 
@@ -1312,6 +1323,99 @@ describe('webhookPlugin signing', () => {
 
 ---
 
+## 9b. Where your plugin's data lives
+
+Plugin-owned data may live in the five storage areas listed below; the
+**current write paths differ by area** and fall into three families:
+
+- **KvStore** — admin/editor write through AppSync. Plugin hooks have no
+  KvStore write helper today.
+- **PluginSecret + PluginSecretIndicator** — written by the
+  `plugin-secret-handler` Lambda, which is invoked by admin/editor through
+  the `setPluginSecret` / `clearPluginSecret` AppSync mutations. The
+  trusted processor reads `PluginSecret` via `ctx.secret<T>()` but does
+  NOT write to either secret table.
+- **S3 `public/plugins/{instanceId ?? name}/*`** — written by the trusted
+  Lambda's hook context (`ctx.writePublicAsset(...)`). This is the only
+  area a plugin hook writes to directly today.
+
+All other areas — the `Post`, `Page`, `Media`, and `PostTag` DynamoDB
+tables, the `public/site-settings.json` S3 mirror, and any other plugin's
+namespace — are off-limits. The runtime does not enforce this today; it is
+a contract enforced by trust (and future IAM hardening).
+
+| Area | Path / identifier | Access level | Phase |
+|---|---|---|---|
+| KvStore (admin settings) | DynamoDB `pk='siteconfig'`, `sk='plugins.<instanceId>.<fieldKey>'` | admin/editor via AppSync; plugin hook write helper is not provided today | Phase 2 |
+| KvStore (runtime state/cache) | DynamoDB `pk='pluginstate:<plugin>:...'` with optional TTL | admin/editor via AppSync; plugin hook write helper is not provided today | Current |
+| PluginSecret | DynamoDB `PluginSecret` table, `sk='plugins.<instanceId>.<fieldKey>'` | `trusted` only (IAM-only AppSync auth) | Phase 6a |
+| PluginSecretIndicator | DynamoDB `PluginSecretIndicator` table, `sk='plugins.<instanceId>.<fieldKey>'` | `trusted` + admin/editor (read indicator) | Phase 6a |
+| S3 plugin assets | `public/plugins/{instanceId ?? name}/*` | `trusted` only (`writePublicAsset`) | Phase 3 |
+
+**Cleanup is not automatic.** Removing a plugin from `cms.config.ts` leaves
+orphan data in all five areas. Manual operator cleanup is required until the
+future lifecycle-dispatch PR ships the invocation mechanism for the `uninstall`
+hook (see §9c below).
+
+**Custom DynamoDB tables.** If your plugin provisions its own DynamoDB table
+outside the ampless schema, lifecycle management (including cleanup on uninstall)
+is your responsibility. ampless has no visibility into external tables and the
+future `uninstall` cleanup grants cover only the five areas above.
+
+See [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#plugin-owned-data-areas)
+for the full rationale and the IAM grant design.
+
+---
+
+## 9c. `uninstall` hook (Phase 1 reservation)
+
+`AmplessPlugin.uninstall` is a **Phase 1 type reservation** — the runtime does
+not call it today. Its purpose is to lock in the hook name and signature before
+any plugin code ships, so the future lifecycle-dispatch PR can wire the
+invocation without renaming or reshaping anything.
+
+**Phase 1 scope**: only the hook name and signature are reserved. The `ctx`
+does **not** yet carry cleanup helpers (`deletePublicAsset` /
+`deletePluginSetting` / `deletePluginSecret`) — writing
+`await ctx.deletePublicAsset(...)` today is a TypeScript error. When those
+helpers land (in the lifecycle-dispatch PR), they are added to
+`PluginUninstallContext` additively, with no breaking change to plugins that
+declared an empty body in advance.
+
+**Recommended declaration today** — an empty body:
+
+```ts
+// Example: a trusted plugin that writes assets and stores secrets
+definePlugin({
+  name: 'my-trusted-plugin',
+  apiVersion: 1,
+  trust_level: 'trusted',
+  capabilities: ['eventHooks', 'writePublicAsset', 'secretSettings'],
+  hooks: { 'content.published': async (_evt, ctx) => { /* ... */ } },
+  uninstall: async (_ctx) => {
+    // Phase 1 reservation: the runtime does not invoke this hook
+    // today, AND `ctx` does not yet carry cleanup helpers
+    // (`deletePublicAsset` / `deletePluginSetting` /
+    // `deletePluginSecret`). Declaring an empty body is the
+    // recommended forward-compat shape — when the future
+    // lifecycle-dispatch PR ships, the helpers land on
+    // `PluginUninstallContext` additively, and you fill in the
+    // body THEN. Plugins that shipped the empty declaration
+    // today do not need to re-publish for the signature change,
+    // but a re-publish is required to add the actual cleanup
+    // body.
+  },
+})
+```
+
+**Idempotency.** When the lifecycle-dispatch PR ships, the `uninstall` hook
+runs in a trusted-Lambda IAM context. The SQS delivery is at-least-once, so
+your cleanup body may run more than once — design it to be safe to retry
+(e.g. `deleteObject` is idempotent on S3; a conditional `delete` on DDB is
+safe if the key is already gone).
+
+---
+
 ## 10. Walk-through: migrating GA4 from Phase 1 to Phase 2
 
 The Phase 1 GA4 plugin took the measurement ID through a

package/dist/templates/_shared/package.json

@@ -25,21 +25,21 @@
     "@tiptap/pm": "^3.23.6",
     "@tiptap/react": "^3.23.6",
     "@tiptap/starter-kit": "^3.23.6",
-    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.18",
-    "@ampless/plugin-cookie-consent": "^0.1.0-alpha.9",
-    "@ampless/plugin-gtm": "^0.2.0-alpha.17",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.34",
-    "@ampless/plugin-plausible": "^0.2.0-alpha.17",
-    "@ampless/plugin-reading-time": "^0.1.0-alpha.7",
-    "@ampless/plugin-rss": "^0.2.0-alpha.34",
-    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.13",
-    "@ampless/plugin-seo": "^0.2.0-alpha.34",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.35",
-    "@ampless/admin": "^1.0.0-alpha.67",
-    "@ampless/backend": "^1.0.0-alpha.56",
-    "@ampless/runtime": "^1.0.0-alpha.43",
+    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.20",
+    "@ampless/plugin-cookie-consent": "^0.1.0-alpha.11",
+    "@ampless/plugin-gtm": "^0.2.0-alpha.19",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.36",
+    "@ampless/plugin-plausible": "^0.2.0-alpha.19",
+    "@ampless/plugin-reading-time": "^0.1.0-alpha.9",
+    "@ampless/plugin-rss": "^0.2.0-alpha.36",
+    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.15",
+    "@ampless/plugin-seo": "^0.2.0-alpha.36",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.37",
+    "@ampless/admin": "^1.0.0-alpha.69",
+    "@ampless/backend": "^1.0.0-alpha.58",
+    "@ampless/runtime": "^1.0.0-alpha.45",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^1.0.0-alpha.34",
+    "ampless": "^1.0.0-alpha.36",
     "aws-amplify": "^6.17.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ampless",
-  "version": "1.0.0-alpha.111",
+  "version": "1.0.0-alpha.115",
   "description": "Create a new ampless project",
   "license": "MIT",
   "type": "module",