create-ampless 1.0.0-alpha.66 → 1.0.0-alpha.69

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

@@ -139,7 +139,7 @@ analyticsGa4Plugin({ instanceId: 'product' })
 | 階層 | IAM | 用途 |
 |---|---|---|
 | `untrusted` | なし (SQS consume のみ) | head/body descriptor、webhook 配送、コンテンツ変換 |
-| `trusted` | 投稿読み出し、`public/plugins/<name>/...` への書き込み | RSS フィード、sitemap、計算済み JSON インデックス |
+| `trusted` | 投稿読み出し、`public/plugins/<instanceId ?? name>/...` への書き込み | RSS フィード、sitemap、計算済み JSON インデックス |
 | `privileged` | 予約 | 将来: SES、secret、private S3 |
 
 決め方の目安:
@@ -273,6 +273,26 @@ hooks: {
 }
 ```
 
+### `writePublicAsset`
+
+公開生成ファイルを書き出す trusted plugin は capability を宣言してください:
+
+```ts
+capabilities: ['eventHooks', 'writePublicAsset']
+```
+
+同じ plugin が `metadata()` または `siteMetadata()` も実装する場合は、`metadata` も宣言します。この capability 名は両方の metadata 関数をまとめて表し、別個の `siteMetadata` capability はありません。
+
+trusted processor は次の場所に書き込みます:
+
+```txt
+public/plugins/<instanceId ?? name>/<key>
+```
+
+`key` は allowlist `[A-Za-z0-9._/-]+` に一致する必要があります。それ以外（スペース、URL 予約文字 `#` `?` `&` `=` `+`、非 ASCII 文字 (`日本語.xml` 等)、空文字、絶対パス（`/` 始まり）、`.` / `..` path segment、backslash、制御文字、256 文字超）は S3 呼び出し前に拒否されます。`indexes/posts.json` のような nested path や `feed.v2.xml` のような複数 dot は許可されます。allowlist を厳しく絞っているのは、返却 URL と実 S3 key を byte 等しい文字列に保つため — URL 予約文字は S3 では生バイトとして通るが、URL を consumer が parse すると別 object を指す状態になる。user 由来の文字を key に入れたい場合は事前に sanitize (hash、slugify 等) してから `ctx.writePublicAsset()` を呼んでください。戻り値は書き込まれた object の public URL です。
+
+移行期間中、`capabilities` フィールドが無い plugin はそのまま動きます。`capabilities` を宣言しているのに `writePublicAsset` を省いた plugin は、実際に `ctx.writePublicAsset()` を呼んだ時に 1 回だけ warn します。
+
 ### ベストプラクティス
 
 - **冪等にする**。SQS は at-least-once 配送 — 同じイベントが 2 回 fire する可能性があります。同じ入力で同じ出力 (決定論的なフィード等) を生成するようにしてください

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

@@ -168,7 +168,7 @@ touch IAM):
 | Tier | IAM | Used by |
 |---|---|---|
 | `untrusted` | none (SQS consume only) | head/body descriptors, webhook delivery, content transforms |
-| `trusted` | read posts, write `public/plugins/<name>/...` | RSS feed, sitemap, computed JSON indexes |
+| `trusted` | read posts, write `public/plugins/<instanceId ?? name>/...` | RSS feed, sitemap, computed JSON indexes |
 | `privileged` | reserved | future: SES, secrets, private S3 |
 
 Rule of thumb:
@@ -332,6 +332,44 @@ hooks: {
 }
 ```
 
+### `writePublicAsset`
+
+Trusted plugins that write public generated files should declare the
+capability:
+
+```ts
+capabilities: ['eventHooks', 'writePublicAsset']
+```
+
+If the same plugin implements `metadata()` or `siteMetadata()`, also
+declare `metadata`. That capability name covers both metadata
+functions; there is no separate `siteMetadata` capability.
+
+The trusted processor writes under:
+
+```txt
+public/plugins/<instanceId ?? name>/<key>
+```
+
+`key` must match the allowlist `[A-Za-z0-9._/-]+`. Anything outside
+that — spaces, URL-reserved characters (`#`, `?`, `&`, `=`, `+`),
+non-ASCII (`日本語.xml`), empty strings, absolute paths (leading `/`),
+`.` / `..` path segments, backslashes, control characters, or keys
+over 256 characters — is rejected before S3 is called. Nested paths
+such as `indexes/posts.json` and dotted extensions such as
+`feed.v2.xml` are allowed. The allowlist is deliberately tight so
+the returned public URL and the underlying S3 key are byte-identical
+strings; URL-reserved characters would survive S3 but reshape the URL
+when a consumer parses it. If you need to include user-supplied
+characters in a key, sanitize first (e.g. hash, slugify) before
+calling `ctx.writePublicAsset()`. The return value is the public URL
+for the written object.
+
+During the migration period, plugins with no `capabilities` field
+keep working. Plugins that do declare `capabilities` but omit
+`writePublicAsset` warn once when they actually call
+`ctx.writePublicAsset()`.
+
 ### Best practices
 
 - **Be idempotent.** SQS delivery is at-least-once: the same event

package/dist/templates/_shared/package.json

@@ -25,18 +25,18 @@
     "@tiptap/pm": "^3.23.6",
     "@tiptap/react": "^3.23.6",
     "@tiptap/starter-kit": "^3.23.6",
-    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.1",
-    "@ampless/plugin-gtm": "^0.1.1-alpha.0",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.18",
-    "@ampless/plugin-plausible": "^0.1.1-alpha.0",
-    "@ampless/plugin-rss": "^0.2.0-alpha.18",
-    "@ampless/plugin-seo": "^0.2.0-alpha.18",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.18",
-    "@ampless/admin": "^1.0.0-alpha.42",
-    "@ampless/backend": "^1.0.0-alpha.33",
-    "@ampless/runtime": "^1.0.0-alpha.24",
+    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.3",
+    "@ampless/plugin-gtm": "^0.1.1-alpha.2",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.20",
+    "@ampless/plugin-plausible": "^0.1.1-alpha.2",
+    "@ampless/plugin-rss": "^0.2.0-alpha.20",
+    "@ampless/plugin-seo": "^0.2.0-alpha.20",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.20",
+    "@ampless/admin": "^1.0.0-alpha.44",
+    "@ampless/backend": "^1.0.0-alpha.35",
+    "@ampless/runtime": "^1.0.0-alpha.26",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^1.0.0-alpha.18",
+    "ampless": "^1.0.0-alpha.20",
     "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.66",
+  "version": "1.0.0-alpha.69",
   "description": "Create a new ampless project",
   "license": "MIT",
   "type": "module",