ampless 1.0.0-alpha.38 → 1.0.0-alpha.40

package/dist/index.d.ts

@@ -973,7 +973,13 @@ interface PluginSettingsManifest {
 }
 interface AmplessPlugin {
     name: string;
-    /** Plugin API version. Currently 1; future versions will be additive. */
+    /**
+     * Plugin API version. Currently `1` is the only supported value.
+     * `apiVersion` is the breaking-change marker on the plugin contract;
+     * additive changes (new optional fields, new reserved capabilities)
+     * stay within `apiVersion: 1`. See the apiVersion bump policy in
+     * `docs/architecture/08-plugin-architecture.md` for the full criteria.
+     */
     apiVersion: 1;
     /**
      * Optional npm package name (e.g. `'@scope/ampless-plugin-foo'` or

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

@@ -172,7 +172,7 @@ export default defineConfig({
 interface AmplessPlugin {
   name: string                      // パッケージ風の識別子。例: 'analytics-ga4'
   packageName?: string              // インストール時のクロスチェック用 npm パッケージ名
-  apiVersion: 1                     // 契約が変わるときだけ bump
+  apiVersion: 1                     // 現状唯一の有効値
   trust_level: 'untrusted' | 'trusted' | 'privileged'
   instanceId?: string               // 複数インストール時の namespace
   displayName?: LocalizedString     // admin UI ラベル
@@ -201,6 +201,12 @@ interface AmplessPlugin {
 
 今日は 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 を持たせる:
@@ -1218,7 +1224,7 @@ it('admin が空文字保存した場合は空配列', () => {
 
 - **パッケージ名**: `@your-scope/plugin-foo`。`@ampless/plugin-*` スコープは本モノレポから ship する公式プラグイン用に予約
 - **エントリ**: ESM のみ、default export (factory) + 設定インターフェイス (ユーザの `cms.config.ts` から型付きで引数を渡せるように) を export
-- **`apiVersion`**: 契約が変わるときだけ bump。既存フィールドの型が変わったら major、新フィールド追加なら minor (既存インストールは動き続ける)
+- **`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/blob/main/docs/architecture/08-plugin-architecture.md#apiversion-bump-policy) を参照
 - **Dist-tag**: ampless 自体が alpha のうちは `@alpha`。`@latest` は ampless v1.0 まで予約
 
 参考実装:
@@ -1334,4 +1340,4 @@ export default defineConfig({
 - ファーストパーティプラグインの bug → `heavymoons/ampless` にプラグインの package 名つきで issue
 - プラグインランタイム / admin form の bug → 同じレポ、ラベル `area:plugins`
 
-ampless レポは v1.0 RC まで非公開なので、上記のリンクは現時点では package tarball 内の `node_modules/ampless/docs/` をローカルで見るための参照です。public 化後は実 GitHub URL に解決されます。
+ampless レポは現在 alpha 期間中は非公開です。beta に進む (npm `beta` dist-tag、リポジトリ公開) と上記のリンクが GitHub URL に解決されます。現状でも同じ docs が package tarball 内の `node_modules/ampless/docs/` に同梱されているので、GitHub にアクセスせずローカルで読めます。

package/docs/plugin-author-guide.md

@@ -200,7 +200,7 @@ That's it. Restart `npm run dev`, view source on any page, and the
 interface AmplessPlugin {
   name: string                      // package-like identifier, e.g. 'analytics-ga4'
   packageName?: string              // npm package name for install-time cross-check
-  apiVersion: 1                     // bump only when the contract changes
+  apiVersion: 1                     // the only valid value today
   trust_level: 'untrusted' | 'trusted' | 'privileged'
   instanceId?: string               // namespace for multi-instance installs
   displayName?: LocalizedString     // admin UI label
@@ -234,6 +234,23 @@ There's only one version today. Future breaking-change versions will
 bump this number; the runtime rejects unknown values rather than
 silently mis-binding.
 
+**Today only `apiVersion: 1` is valid.** The literal type accepts
+no other value, and the runtime hard-throws if `package.json#amplessPlugin.apiVersion`
+disagrees with what `definePlugin()` returns or exceeds the runtime's
+`SUPPORTED_API_VERSION`.
+
+All Phase 1 compat-break reservations (PRs #220, #222, #230, #232,
+#234) live within `apiVersion: 1` — declaring or not declaring them
+in your plugin does not affect the contract version.
+
+If a future `apiVersion: 2` is ever introduced, it will be announced
+through a changeset and a section update in this guide and the
+architecture doc. Until then, **publish your plugin with
+`apiVersion: 1` and treat it as the only valid value**. See the
+[apiVersion bump policy](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#apiversion-bump-policy)
+section in the architecture doc for the full criteria around what
+would (and would not) trigger a v2 bump.
+
 ### `instanceId`
 
 Optional, defaults to `name`. When you ship a plugin that can run
@@ -1641,9 +1658,14 @@ a normal npm package:
   monorepo.
 - **Entry**: ESM only, exports default (the factory) and the
   config interface (for typed args in user `cms.config.ts`).
-- **`apiVersion`**: bump only when the contract changes. Bump
-  major when an existing field's type changes; bump minor when you
-  add a new field (existing installs keep working).
+- **`apiVersion`**: declare `1` today — it is the only valid
+  value, and the literal type rejects others at compile time.
+  `apiVersion` is the breaking-change marker on the plugin
+  contract, not a semver-style channel: additive changes (new
+  optional fields, new reserved capabilities) stay within
+  `apiVersion: 1` and do NOT require a bump. See the [apiVersion
+  bump policy](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#apiversion-bump-policy)
+  in the architecture doc for the full criteria.
 - **Dist-tag**: `@alpha` while ampless itself is in alpha. The
   `@latest` tag stays reserved until ampless v1.0.
 
@@ -1804,6 +1826,8 @@ PROTECTED), so the scaffolded code is safe across ampless upgrades.
 - Bugs in the plugin runtime / admin form → same repo, label
   `area:plugins`.
 
-The ampless repo stays private until v1.0 RC. Once it's public, the
-links above resolve to the actual GitHub URLs; today they live in
-the package tarball directly under `node_modules/ampless/docs/`.
+The ampless repo is currently private during the alpha stage; the
+GitHub URLs above start resolving once beta ships (npm `beta`
+dist-tag, repo flips public). Today the same docs also live in the
+package tarball directly under `node_modules/ampless/docs/`, so
+you can read them locally without browsing GitHub.

package/package.json

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