ampless 1.0.0-beta.61 → 1.0.0-beta.63
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +22 -4
- package/dist/index.js +2 -2
- package/docs/plugin-author-guide.ja.md +10 -10
- package/docs/plugin-author-guide.md +10 -10
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -384,7 +384,7 @@ interface PluginPublicRenderContext {
|
|
|
384
384
|
* and renders the surviving descriptors as React elements inside the
|
|
385
385
|
* root layout's `<head>`. Returning arbitrary `ReactNode` is
|
|
386
386
|
* intentionally not offered here — see
|
|
387
|
-
* `
|
|
387
|
+
* `https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture` §"Descriptor-based
|
|
388
388
|
* Head/Body Injection".
|
|
389
389
|
*/
|
|
390
390
|
type PublicHeadDescriptor = {
|
|
@@ -486,7 +486,7 @@ type PublicHeadDescriptor = {
|
|
|
486
486
|
* an admin installs a plugin, accepting whatever it eventually
|
|
487
487
|
* renders into `<head>` / `<body>`. The boundary is structurally
|
|
488
488
|
* the same as the [editor trust
|
|
489
|
-
* model](
|
|
489
|
+
* model](https://github.com/heavymoons/ampless/wiki/architecture-04-access-layer-mcp#editor-trust-model-specification)
|
|
490
490
|
* — editors can already inject arbitrary `<script>` via post
|
|
491
491
|
* body anyway, so a per-plugin sandbox here wouldn't change the
|
|
492
492
|
* upper bound. If a tighter sandbox is needed, scope it at
|
|
@@ -1166,7 +1166,7 @@ interface AmplessPlugin {
|
|
|
1166
1166
|
* `apiVersion` is the breaking-change marker on the plugin contract;
|
|
1167
1167
|
* additive changes (new optional fields, new reserved capabilities)
|
|
1168
1168
|
* stay within `apiVersion: 1`. See the apiVersion bump policy in
|
|
1169
|
-
* `
|
|
1169
|
+
* `https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture` for the full criteria.
|
|
1170
1170
|
*/
|
|
1171
1171
|
apiVersion: 1;
|
|
1172
1172
|
/**
|
|
@@ -1252,7 +1252,7 @@ interface AmplessPlugin {
|
|
|
1252
1252
|
* What this reservation locks in: when `uninstall` does fire,
|
|
1253
1253
|
* it runs in a trusted-Lambda IAM context with cleanup grants for
|
|
1254
1254
|
* the five plugin-owned data areas (see
|
|
1255
|
-
*
|
|
1255
|
+
* https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture
|
|
1256
1256
|
* §"Plugin-owned data areas"). Idempotency is the plugin author's
|
|
1257
1257
|
* responsibility — the hook may be invoked more than once
|
|
1258
1258
|
* (SQS at-least-once or operator-retry).
|
|
@@ -1669,6 +1669,24 @@ interface AiConfig {
|
|
|
1669
1669
|
* abuse protection.
|
|
1670
1670
|
*/
|
|
1671
1671
|
publicMcp?: boolean;
|
|
1672
|
+
/**
|
|
1673
|
+
* **Experimental.** Publish MCP discovery metadata so AI clients can
|
|
1674
|
+
* find the public endpoint without being handed its URL: a well-known
|
|
1675
|
+
* catalog at `/.well-known/mcp/catalog.json` and a Server Card at
|
|
1676
|
+
* `/api/mcp/server-card`. Requires `publicMcp: true` (discovery only
|
|
1677
|
+
* advertises the same `/api/mcp` endpoint) and an `http(s)` `site.url`
|
|
1678
|
+
* to resolve the absolute URLs it advertises — when either is missing
|
|
1679
|
+
* the discovery routes 404.
|
|
1680
|
+
*
|
|
1681
|
+
* **Default: false.** This tracks the prototype
|
|
1682
|
+
* `modelcontextprotocol/experimental-ext-server-card` spec (SEP-2127 —
|
|
1683
|
+
* still open / unmerged), whose schema and paths may change to follow
|
|
1684
|
+
* upstream, so it is isolated behind this opt-in flag. When enabled,
|
|
1685
|
+
* the `/api/mcp` `initialize` response's `serverInfo` also switches to
|
|
1686
|
+
* a site-derived reverse-DNS name + version so it matches the Server
|
|
1687
|
+
* Card (default OFF sites keep the static `ampless-mcp` serverInfo).
|
|
1688
|
+
*/
|
|
1689
|
+
mcpDiscovery?: boolean;
|
|
1672
1690
|
}
|
|
1673
1691
|
type Role = 'reader' | 'editor' | 'admin';
|
|
1674
1692
|
interface AuthContext {
|
package/dist/index.js
CHANGED
|
@@ -251,7 +251,7 @@ function resolvePublicMcpEndpoint(publicMcp, siteUrl) {
|
|
|
251
251
|
try {
|
|
252
252
|
const parsed = new URL(siteUrl);
|
|
253
253
|
if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
|
|
254
|
-
return new URL("/api/mcp", parsed).toString();
|
|
254
|
+
return new URL("/api/mcp", parsed.origin).toString();
|
|
255
255
|
} catch {
|
|
256
256
|
return null;
|
|
257
257
|
}
|
|
@@ -285,7 +285,7 @@ function definePlugin(p) {
|
|
|
285
285
|
const hasHooks = p.hooks && Object.keys(p.hooks).length > 0 || (p.capabilities?.includes("eventHooks") ?? false);
|
|
286
286
|
if (hasHooks) {
|
|
287
287
|
console.warn(
|
|
288
|
-
`[ampless] Plugin "${p.name}" declares trust_level: 'privileged' with event hooks, but no privileged Lambda is provisioned yet. Hooks will not execute. Sync render surfaces (publicHead / metadata / publicBodyForPost / etc.) work normally regardless of trust_level. See
|
|
288
|
+
`[ampless] Plugin "${p.name}" declares trust_level: 'privileged' with event hooks, but no privileged Lambda is provisioned yet. Hooks will not execute. Sync render surfaces (publicHead / metadata / publicBodyForPost / etc.) work normally regardless of trust_level. See https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture#trust-levels for the future plan.`
|
|
289
289
|
);
|
|
290
290
|
}
|
|
291
291
|
}
|
|
@@ -11,9 +11,9 @@
|
|
|
11
11
|
|
|
12
12
|
このガイドは、初めての `definePlugin()` 呼び出しから admin 編集可能な設定パネル、そして npm 公開に至るまで、ampless プラグインを ship するために必要な手順を一通りカバーします。Phase 1〜4 の機能を網羅 — descriptor ベースの `<head>` / `<body>` / 投稿単位 body 注入、非同期イベントフック、admin 管理の `settings.public` 値です。
|
|
13
13
|
|
|
14
|
-
設計の経緯と背景は [`
|
|
14
|
+
設計の経緯と背景は [`architecture-08-plugin-architecture`](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture) に集約。本ページはその実装ハンドブック側です。
|
|
15
15
|
|
|
16
|
-
> **ポジショニング**: 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 は [`
|
|
16
|
+
> **ポジショニング**: 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 は [`architecture-08-plugin-architecture`](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture#trust-model-v1-scope) を参照してください。
|
|
17
17
|
|
|
18
18
|
---
|
|
19
19
|
|
|
@@ -43,7 +43,7 @@ ampless はテーマとプラグインの両方を提供します。用途に合
|
|
|
43
43
|
- **ストレージ / DynamoDB / 外部 API 書き込みはプラグインに置く**。テーマは読み取り専用です。
|
|
44
44
|
- **admin が `/admin/plugins` からオン・オフしたい機能はプラグインに置く**。表面上の効果が純粋に見た目だけであっても同様です。テーマも独自の設定を持てますが、それはテーマ表示設定であり、サイト運用設定ではありません。
|
|
45
45
|
|
|
46
|
-
境界線上に本当に乗っている機能については [`
|
|
46
|
+
境界線上に本当に乗っている機能については [`architecture-08-plugin-architecture`](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture) で詳しく議論しています。
|
|
47
47
|
|
|
48
48
|
---
|
|
49
49
|
|
|
@@ -208,7 +208,7 @@ interface AmplessPlugin {
|
|
|
208
208
|
|
|
209
209
|
Phase 1 の compat-break reservation すべて(PR #220、#222、#230、#232、#234)は `apiVersion: 1` 内に収まります。これらをプラグインで declare するかどうかは契約バージョンに影響しません。
|
|
210
210
|
|
|
211
|
-
将来 `apiVersion: 2` が導入される場合は、changeset とこのガイドおよび architecture doc のセクション更新を通じてアナウンスされます。それまでは、**`apiVersion: 1` でプラグインを publish し、唯一の有効値として扱ってください**。v2 bump の trigger となるもの(ならないもの)の全基準については、architecture doc の [apiVersion bump policy](https://github.com/heavymoons/ampless/
|
|
211
|
+
将来 `apiVersion: 2` が導入される場合は、changeset とこのガイドおよび architecture doc のセクション更新を通じてアナウンスされます。それまでは、**`apiVersion: 1` でプラグインを publish し、唯一の有効値として扱ってください**。v2 bump の trigger となるもの(ならないもの)の全基準については、architecture doc の [apiVersion bump policy](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture#apiversion-bump-policy) セクションを参照してください。
|
|
212
212
|
|
|
213
213
|
### `instanceId`
|
|
214
214
|
|
|
@@ -290,7 +290,7 @@ runtime がチェックする内容:
|
|
|
290
290
|
|
|
291
291
|
## 4. `trust_level` の選び方
|
|
292
292
|
|
|
293
|
-
trust 階層は v1 において**ファーストパーティプラグインの code organization**として実装されています — イベントフックがどの IAM スコープ付き Lambda で実行されるか、その Lambda が保有する権限を決定します。これはエンジニアが審査した npm dep 向けの code organization surface であり、任意のサードパーティ未審査プラグインを自動的に安全に動かすための marketplace-grade automatic sandbox ではありません(上記の[ポジショニング注記](#ampless-プラグインの書き方)と[詳細な trust model](https://github.com/heavymoons/ampless/
|
|
293
|
+
trust 階層は v1 において**ファーストパーティプラグインの code organization**として実装されています — イベントフックがどの IAM スコープ付き Lambda で実行されるか、その Lambda が保有する権限を決定します。これはエンジニアが審査した npm dep 向けの code organization surface であり、任意のサードパーティ未審査プラグインを自動的に安全に動かすための marketplace-grade automatic sandbox ではありません(上記の[ポジショニング注記](#ampless-プラグインの書き方)と[詳細な trust model](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture#trust-model-v1-scope) を参照)。
|
|
294
294
|
|
|
295
295
|
3 階層、選択基準は **イベントフック (hooks) が何を必要とするか** で決まります (sync サーフェスは IAM に触れない):
|
|
296
296
|
|
|
@@ -641,7 +641,7 @@ hooks: {
|
|
|
641
641
|
|
|
642
642
|
`content.published` の発火を保存時ではなく `publishedAt` のタイミングに合わせる機能 — EventBridge Scheduler または DynamoDB TTL トリガー Lambda によるスケジューラーコンポーネントが必要 — は計画中の機能強化です。現リリースのスコープには含まれていません。それまでの間は上記のパターンが通知プラグインにおける推奨ガードです。
|
|
643
643
|
|
|
644
|
-
オペレーター視点からの `publishedAt` セマンティクスの全体像は [`
|
|
644
|
+
オペレーター視点からの `publishedAt` セマンティクスの全体像は [`scheduled-publishing`](https://github.com/heavymoons/ampless/wiki/scheduled-publishing.ja) を参照してください。
|
|
645
645
|
|
|
646
646
|
---
|
|
647
647
|
|
|
@@ -1201,7 +1201,7 @@ public/plugins/<instanceId ?? name>/<key>
|
|
|
1201
1201
|
### ベストプラクティス
|
|
1202
1202
|
|
|
1203
1203
|
- **冪等にする**。SQS は at-least-once 配送 — 同じイベントが 2 回 fire する可能性があります。同じ入力で同じ出力 (決定論的なフィード等) を生成するようにしてください
|
|
1204
|
-
- **宣言していない `event.payload.*` を読まない**。形は [`
|
|
1204
|
+
- **宣言していない `event.payload.*` を読まない**。形は [`architecture-05-event-system`](https://github.com/heavymoons/ampless/wiki/architecture-05-event-system) に文書化されています。形がドリフトすると暗黙の読み出しが silent に壊れます
|
|
1205
1205
|
- **エラーは DLQ に行く**。フック内で throw すると最終的にメッセージは dead-letter queue に届きます。失敗のサーフェスは通常の CloudWatch ダッシュボードで
|
|
1206
1206
|
|
|
1207
1207
|
---
|
|
@@ -1463,7 +1463,7 @@ admin は再デプロイなしにいつでも secret をローテーションで
|
|
|
1463
1463
|
|
|
1464
1464
|
**独自 DynamoDB テーブル。** プラグインが ampless スキーマ外に独自の DynamoDB テーブルを持つ場合、lifecycle 管理(アンインストール時の cleanup を含む)はプラグイン著者の責任です。ampless は外部テーブルを把握しておらず、将来の `uninstall` cleanup grant は上記 5 領域のみをカバーします。
|
|
1465
1465
|
|
|
1466
|
-
詳細な設計根拠と IAM grant 設計については [`
|
|
1466
|
+
詳細な設計根拠と IAM grant 設計については [`architecture-08-plugin-architecture.ja`](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture.ja#プラグインが所有するデータ領域) を参照してください。
|
|
1467
1467
|
|
|
1468
1468
|
---
|
|
1469
1469
|
|
|
@@ -1682,7 +1682,7 @@ it('admin が空文字保存した場合は空配列', () => {
|
|
|
1682
1682
|
|
|
1683
1683
|
- **パッケージ名**: `@your-scope/plugin-foo`。`@ampless/plugin-*` スコープは本モノレポから ship する公式プラグイン用に予約
|
|
1684
1684
|
- **エントリ**: ESM のみ、default export (factory) + 設定インターフェイス (ユーザの `cms.config.ts` から型付きで引数を渡せるように) を export
|
|
1685
|
-
- **`apiVersion`**: 現状は `1` を declare してください — 唯一の有効値で、literal type が他の値を compile-time に reject します。`apiVersion` はプラグイン契約の **breaking-change marker** であって semver 風のチャンネルではありません。additive な追加 (optional field、reserved capability など) は `apiVersion: 1` 内に収まり、bump は不要です。詳細は architecture doc の [apiVersion bump policy](https://github.com/heavymoons/ampless/
|
|
1685
|
+
- **`apiVersion`**: 現状は `1` を declare してください — 唯一の有効値で、literal type が他の値を compile-time に reject します。`apiVersion` はプラグイン契約の **breaking-change marker** であって semver 風のチャンネルではありません。additive な追加 (optional field、reserved capability など) は `apiVersion: 1` 内に収まり、bump は不要です。詳細は architecture doc の [apiVersion bump policy](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture#apiversion-bump-policy) を参照
|
|
1686
1686
|
- **Dist-tag**: ampless 自体が beta のうちは `@beta`。`@latest` は ampless v1.0 まで予約
|
|
1687
1687
|
|
|
1688
1688
|
参考実装:
|
|
@@ -1796,7 +1796,7 @@ export default defineConfig({
|
|
|
1796
1796
|
|
|
1797
1797
|
## 15. 質問先
|
|
1798
1798
|
|
|
1799
|
-
- アーキテクチャ / 設計の質問 → [`
|
|
1799
|
+
- アーキテクチャ / 設計の質問 → [`architecture-08-plugin-architecture.ja`](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture.ja)
|
|
1800
1800
|
- ファーストパーティプラグインの bug → `heavymoons/ampless` にプラグインの package 名つきで issue
|
|
1801
1801
|
- プラグインランタイム / admin form の bug → 同じレポ、ラベル `area:plugins`
|
|
1802
1802
|
|
|
@@ -16,10 +16,10 @@ Phase 1–4 surfaces — descriptor-based `<head>` / `<body>` /
|
|
|
16
16
|
per-post body injection, the async event hooks, and admin-managed
|
|
17
17
|
`settings.public` values.
|
|
18
18
|
|
|
19
|
-
The design rationale is in [`
|
|
19
|
+
The design rationale is in [`architecture-08-plugin-architecture`](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture);
|
|
20
20
|
this page is the hands-on companion.
|
|
21
21
|
|
|
22
|
-
> **Positioning**: ampless is a customization-based CMS for engineers — plugins are **npm dependencies that the site engineer imports + configures in `cms.config.ts`**. The engineer audits each dep before installing, the way they would for any other npm library (Astro integration / Next.js plugin pattern). The trust framework described in this guide (`trust_level`, capabilities, IAM-scoped Lambdas) is implemented in v1 as **first-party plugin organization** — it decides which trust tier's Lambda runs each event hook, which IAM permissions each tier holds, and applies hard runtime gates only at narrowly-scoped points (most notably: `settings.secret` requires `trust_level: 'trusted'` because secret read needs the trusted Lambda's IAM permission). Most capability declarations are soft warnings + admin labels + future allow-list surfaces, not hard runtime gates. It is **not** designed as a marketplace-grade automatic sandbox that safely runs arbitrary untrusted third-party plugins. Marketplace + runtime sandbox is a v2.0+ exploration, not a v1 guarantee. See [`
|
|
22
|
+
> **Positioning**: ampless is a customization-based CMS for engineers — plugins are **npm dependencies that the site engineer imports + configures in `cms.config.ts`**. The engineer audits each dep before installing, the way they would for any other npm library (Astro integration / Next.js plugin pattern). The trust framework described in this guide (`trust_level`, capabilities, IAM-scoped Lambdas) is implemented in v1 as **first-party plugin organization** — it decides which trust tier's Lambda runs each event hook, which IAM permissions each tier holds, and applies hard runtime gates only at narrowly-scoped points (most notably: `settings.secret` requires `trust_level: 'trusted'` because secret read needs the trusted Lambda's IAM permission). Most capability declarations are soft warnings + admin labels + future allow-list surfaces, not hard runtime gates. It is **not** designed as a marketplace-grade automatic sandbox that safely runs arbitrary untrusted third-party plugins. Marketplace + runtime sandbox is a v2.0+ exploration, not a v1 guarantee. See [`architecture-08-plugin-architecture`](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture#trust-model-v1-scope) for the full trust model.
|
|
23
23
|
|
|
24
24
|
---
|
|
25
25
|
|
|
@@ -56,7 +56,7 @@ The two boundaries that frequently catch new authors:
|
|
|
56
56
|
carry their own settings, but those are theme-display settings, not
|
|
57
57
|
site-operational ones.
|
|
58
58
|
|
|
59
|
-
Some features genuinely sit at the boundary — see [`
|
|
59
|
+
Some features genuinely sit at the boundary — see [`architecture-08-plugin-architecture`](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture)
|
|
60
60
|
for the longer discussion.
|
|
61
61
|
|
|
62
62
|
---
|
|
@@ -250,7 +250,7 @@ If a future `apiVersion: 2` is ever introduced, it will be announced
|
|
|
250
250
|
through a changeset and a section update in this guide and the
|
|
251
251
|
architecture doc. Until then, **publish your plugin with
|
|
252
252
|
`apiVersion: 1` and treat it as the only valid value**. See the
|
|
253
|
-
[apiVersion bump policy](https://github.com/heavymoons/ampless/
|
|
253
|
+
[apiVersion bump policy](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture#apiversion-bump-policy)
|
|
254
254
|
section in the architecture doc for the full criteria around what
|
|
255
255
|
would (and would not) trigger a v2 bump.
|
|
256
256
|
|
|
@@ -361,7 +361,7 @@ not a runtime block.
|
|
|
361
361
|
|
|
362
362
|
## 4. Picking a `trust_level`
|
|
363
363
|
|
|
364
|
-
The trust tiers are implemented in v1 as **first-party plugin organization** — they decide which IAM-scoped Lambda runs your event hooks and which permissions that Lambda holds. This is a code organization surface for engineer-audited npm deps, not a marketplace-grade automatic sandbox for arbitrary third-party untrusted plugins (see the [Positioning note](#writing-an-ampless-plugin) above and the [full trust model](https://github.com/heavymoons/ampless/
|
|
364
|
+
The trust tiers are implemented in v1 as **first-party plugin organization** — they decide which IAM-scoped Lambda runs your event hooks and which permissions that Lambda holds. This is a code organization surface for engineer-audited npm deps, not a marketplace-grade automatic sandbox for arbitrary third-party untrusted plugins (see the [Positioning note](#writing-an-ampless-plugin) above and the [full trust model](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture#trust-model-v1-scope)).
|
|
365
365
|
|
|
366
366
|
Three tiers, picked by what the plugin needs to do **inside
|
|
367
367
|
event hooks** (the sync surfaces — metadata, head, body — don't
|
|
@@ -843,7 +843,7 @@ current release. Until then, the pattern above is the recommended
|
|
|
843
843
|
guard for notification plugins.
|
|
844
844
|
|
|
845
845
|
For a full description of `publishedAt` semantics from the operator's
|
|
846
|
-
perspective, see [`
|
|
846
|
+
perspective, see [`scheduled-publishing`](https://github.com/heavymoons/ampless/wiki/scheduled-publishing).
|
|
847
847
|
|
|
848
848
|
---
|
|
849
849
|
|
|
@@ -1622,7 +1622,7 @@ keep working. Plugins that do declare `capabilities` but omit
|
|
|
1622
1622
|
may fire twice. Writing the same output twice should produce the
|
|
1623
1623
|
same effect (e.g. a deterministic feed).
|
|
1624
1624
|
- **Don't read events.payload.\* fields you didn't declare.** The
|
|
1625
|
-
shape is documented in [`
|
|
1625
|
+
shape is documented in [`architecture-05-event-system`](https://github.com/heavymoons/ampless/wiki/architecture-05-event-system);
|
|
1626
1626
|
drifting consumers break silently when the shape moves.
|
|
1627
1627
|
- **Errors propagate to DLQ.** Throwing inside a hook eventually
|
|
1628
1628
|
parks the message in the dead-letter queue. Use the normal
|
|
@@ -2025,7 +2025,7 @@ outside the ampless schema, lifecycle management (including cleanup on uninstall
|
|
|
2025
2025
|
is your responsibility. ampless has no visibility into external tables and the
|
|
2026
2026
|
future `uninstall` cleanup grants cover only the five areas above.
|
|
2027
2027
|
|
|
2028
|
-
See [`
|
|
2028
|
+
See [`architecture-08-plugin-architecture`](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture#plugin-owned-data-areas)
|
|
2029
2029
|
for the full rationale and the IAM grant design.
|
|
2030
2030
|
|
|
2031
2031
|
---
|
|
@@ -2306,7 +2306,7 @@ a normal npm package:
|
|
|
2306
2306
|
contract, not a semver-style channel: additive changes (new
|
|
2307
2307
|
optional fields, new reserved capabilities) stay within
|
|
2308
2308
|
`apiVersion: 1` and do NOT require a bump. See the [apiVersion
|
|
2309
|
-
bump policy](https://github.com/heavymoons/ampless/
|
|
2309
|
+
bump policy](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture#apiversion-bump-policy)
|
|
2310
2310
|
in the architecture doc for the full criteria.
|
|
2311
2311
|
- **Dist-tag**: `@beta` while ampless itself is in beta. The
|
|
2312
2312
|
`@latest` tag stays reserved until ampless v1.0.
|
|
@@ -2464,7 +2464,7 @@ PROTECTED), so the scaffolded code is safe across ampless upgrades.
|
|
|
2464
2464
|
|
|
2465
2465
|
## 15. Where to ask
|
|
2466
2466
|
|
|
2467
|
-
- Architecture / design questions → [`
|
|
2467
|
+
- Architecture / design questions → [`architecture-08-plugin-architecture`](https://github.com/heavymoons/ampless/wiki/architecture-08-plugin-architecture)
|
|
2468
2468
|
- Bugs in a first-party plugin → file an issue against
|
|
2469
2469
|
`heavymoons/ampless` referencing the plugin's package name.
|
|
2470
2470
|
- Bugs in the plugin runtime / admin form → same repo, label
|