ampless 1.0.0-alpha.35 → 1.0.0-alpha.36

package/dist/index.d.ts

@@ -633,6 +633,28 @@ interface PluginRuntimeContext {
      */
     writePublicAsset(key: string, body: string | Uint8Array, contentType: string): Promise<string>;
 }
+/**
+ * Context passed to the `uninstall` lifecycle hook (Phase 1
+ * reservation: runtime no-op — see `AmplessPlugin.uninstall`).
+ *
+ * Phase 1: structurally identical to `PluginRuntimeContext`. The
+ * dedicated type exists so future cleanup helpers
+ * (`deletePublicAsset`, `deletePluginSetting`, `deletePluginSecret`)
+ * can be added here without exposing them to regular event hooks,
+ * which take `PluginRuntimeContext` and should not be able to
+ * delete state from arbitrary plugin areas.
+ *
+ * Phase 1 scope is limited to: (a) reserving the type name, (b)
+ * reserving the hook signature `(ctx: PluginUninstallContext) =>
+ * Promise<void>`. Cleanup helper methods are NOT included in
+ * Phase 1 — plugin authors writing `await ctx.deletePublicAsset(...)`
+ * today would hit a TS error. The actual cleanup body lands when
+ * the future lifecycle-dispatch PR adds the helper methods to this
+ * type (additive, no breaking change for plugins that declared an
+ * empty `uninstall` body in advance).
+ */
+interface PluginUninstallContext extends PluginRuntimeContext {
+}
 /**
  * Extended runtime context for **trusted** hook handlers. Adds
  * `secret<T>(key)` — an async accessor that reads from the isolated
@@ -934,6 +956,52 @@ interface AmplessPlugin {
     hooks?: {
         [K in EventType]?: PluginEventHandler<K>;
     };
+    /**
+     * Lifecycle hook called when this plugin is removed from
+     * `cms.config.ts` (Phase 1 reservation: runtime no-op).
+     *
+     * Today the runtime does not detect plugin removal and does not
+     * invoke this hook — orphan data left behind by an uninstalled
+     * plugin must be cleaned up manually by the operator. A future
+     * lifecycle-dispatch PR will need to solve the underlying
+     * problem that a plugin that has been deleted from `cms.config.ts`
+     * no longer has a callable factory in memory — `Config.plugins`
+     * (see `packages/ampless/src/types.ts`) only carries currently-
+     * active plugin objects. Possible future approaches:
+     *
+     *   - Two-stage `cms.config.ts` flag — `{ plugin: myPlugin(), pendingRemoval: true }`
+     *     keeps the plugin loadable while the runtime calls `uninstall`,
+     *     then the operator removes the entry once cleanup succeeds.
+     *   - Explicit `npx ampless uninstall <name>` CLI command — keeps
+     *     the plugin imported during the call by reading the prior
+     *     `cms.config.ts` entry, fires `uninstall`, then mutates the
+     *     file.
+     *   - Persist prior manifest + `packageName` to DDB/disk so the
+     *     runtime can `await import(packageName)` to re-acquire the
+     *     factory — assumes the npm package is still installed.
+     *
+     * The exact mechanism is deferred to the lifecycle-dispatch PR.
+     * What this reservation locks in: when `uninstall` does fire,
+     * it runs in a trusted-Lambda IAM context with cleanup grants for
+     * the five plugin-owned data areas (see
+     * docs/architecture/08-plugin-architecture.md
+     * §"Plugin-owned data areas"). Idempotency is the plugin author's
+     * responsibility — the hook may be invoked more than once
+     * (SQS at-least-once or operator-retry).
+     *
+     * **Phase 1 reservation 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 TS error. The recommended Phase 1 declaration is an
+     * **empty body** (`async (_ctx) => {}`); the actual cleanup body
+     * lands when the lifecycle-dispatch PR adds the helpers. Plugins
+     * that declared the empty-body uninstall today will pick up the
+     * cleanup invocation events without re-publishing for the signature
+     * change, but a re-publish is required to add the actual cleanup
+     * body.
+     */
+    uninstall?: (ctx: PluginUninstallContext) => Promise<void>;
     /**
      * Per-post metadata generator. Pure function, called from Next.js
      * generateMetadata(). Must not have side effects.
@@ -1551,4 +1619,4 @@ declare function pickDefaultEntrypoint(files: readonly {
 
 declare const VERSION = "0.0.1";
 
-export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginHookResult, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };
+export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginHookResult, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUninstallContext, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };

package/docs/plugin-author-guide.ja.md

@@ -973,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/docs/plugin-author-guide.md

@@ -1323,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ampless",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",