@kubohiroya/sb3-toolchain 0.2.0 → 0.3.0

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/README.md CHANGED
@@ -8,6 +8,7 @@ expanded sources and rebuilding bit-for-bit identical SB3 files from the same in
8
8
  - Safely expand an SB3 into formatted `project.source.json`, assets, and embedded extensions
9
9
  - Validate asset references, MD5 hashes, ZIP entries, and embedded extension mappings
10
10
  - Record commits and SHA-256 hashes for GitHub-hosted embedded extensions and verify them offline
11
+ - Optionally compare versioned extension API manifests before replacing embedded JavaScript
11
12
  - Statically bundle multiple extensions into one permission unit without deleting their original
12
13
  JavaScript, then restore them from either the expanded source or the bundled SB3
13
14
  - Produce deterministic builds with fixed ZIP entry order, timestamps, and compression settings
@@ -28,7 +29,7 @@ TurboWarp Packager are outside the scope of this package.
28
29
  Pin the verified npm version for reproducible installation.
29
30
 
30
31
  ```bash
31
- pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.2.0
32
+ pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.3.0
32
33
  ```
33
34
 
34
35
  ## Quick start
@@ -99,8 +100,11 @@ await updateExtensions({
99
100
  extensionId: 'oldId',
100
101
  migrateToId: 'newid',
101
102
  sourceArtifact: 'dist/newid.js',
103
+ apiManifestArtifact: 'dist/newid.manifest.json',
102
104
  yes: true,
103
105
  });
106
+ // After reviewing a reported breaking API change, opt in explicitly:
107
+ await updateExtensions({sourceDirectory: 'app', allowBreakingApi: true, yes: true});
104
108
  await bundleExtensions({
105
109
  sourceDirectory: 'app',
106
110
  bundleId: 'projectbundle',
@@ -126,6 +130,7 @@ await unbundleSb3({
126
130
  - [`docs/workflows.md`](docs/workflows.md): SB3 source and extension management workflows
127
131
  - [`docs/source-format-v1.md`](docs/source-format-v1.md): expanded source format and deterministic output
128
132
  - [`docs/extension-id-migration.md`](docs/extension-id-migration.md): migration of extension IDs already used by a project
133
+ - [`docs/extension-api-compatibility.md`](docs/extension-api-compatibility.md) ([日本語](docs/ja/extension-api-compatibility.md)): opt-in static API compatibility checks for extension updates
129
134
  - [`docs/extension-bundles.md`](docs/extension-bundles.md): static bundling into one permission unit and reversible unbundling
130
135
 
131
136
  ## Development
@@ -0,0 +1,169 @@
1
+ # Extension API compatibility manifests
2
+
3
+ [日本語版](ja/extension-api-compatibility.md)
4
+
5
+ An embedded extension can opt in to a versioned API manifest so that `sb3-toolchain` checks the
6
+ saved-project contract before replacing its JavaScript. The manifest is validation metadata: it is
7
+ kept in expanded source, fetched from the same immutable commit as the JavaScript, and never embedded
8
+ in the generated SB3.
9
+
10
+ This feature is optional. Existing unmanaged extensions and managed extensions without
11
+ `source.apiManifest` keep their previous behavior and deterministic SB3 output.
12
+
13
+ ## Why a second artifact is necessary
14
+
15
+ Commit pinning and SHA-256 answer whether a JavaScript artifact is authentic and reproducible. They
16
+ do not answer whether an update still provides the opcodes and argument shapes already stored in a
17
+ project.
18
+
19
+ ```mermaid
20
+ flowchart LR
21
+ Ref["Tracked Git ref"] --> Commit["Resolved commit"]
22
+ Commit --> JS["Extension JavaScript"]
23
+ Commit --> API["API manifest v1"]
24
+ JS --> Identity["Header ID + SHA-256"]
25
+ API --> Contract["Opcode / argument / menu comparison"]
26
+ Identity --> Candidate["Validated candidate"]
27
+ Contract --> Candidate
28
+ Candidate --> Transaction["One transactional source update"]
29
+ ```
30
+
31
+ The manifest is parsed as JSON and is never executed. `sb3-toolchain` validates manifest v1 locally
32
+ instead of downloading a schema during a check or build.
33
+
34
+ ## Expanded-source metadata
35
+
36
+ Add `apiManifest` below an existing GitHub `source` object:
37
+
38
+ ```json
39
+ {
40
+ "id": "example",
41
+ "path": "extensions/example.js",
42
+ "mediaType": "text/javascript",
43
+ "parameters": [],
44
+ "encoding": "base64",
45
+ "source": {
46
+ "provider": "github",
47
+ "repository": "owner/example-extension",
48
+ "ref": "main",
49
+ "resolvedCommit": "0123456789abcdef0123456789abcdef01234567",
50
+ "artifact": "dist/example.js",
51
+ "integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
52
+ "apiManifest": {
53
+ "artifact": "dist/extension-manifest.json",
54
+ "path": "extensions/example.manifest.json",
55
+ "formatVersion": 1,
56
+ "integrity": "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="
57
+ }
58
+ }
59
+ }
60
+ ```
61
+
62
+ - `artifact` is the manifest path in the GitHub repository.
63
+ - `path` must be `extensions/<extensionId>.manifest.json` in expanded source.
64
+ - `formatVersion` must be `1`.
65
+ - `integrity` is the SHA-256 SRI value of the installed manifest file.
66
+
67
+ The JavaScript and manifest artifacts use the same repository and `resolvedCommit`. Separate
68
+ repositories or commits are intentionally unsupported because they would make the recorded API
69
+ contract ambiguous.
70
+
71
+ ## Manifest v1 contract
72
+
73
+ Manifest v1 contains:
74
+
75
+ - the extension ID;
76
+ - block opcode and block type;
77
+ - argument ID, type, and optional menu reference;
78
+ - menu ID and `acceptReporters`.
79
+
80
+ Unknown properties, duplicate identifiers, unknown menu references, unsupported versions, and ID
81
+ mismatches are rejected. Array order is normalized before comparison.
82
+
83
+ Display text, descriptions, default values, static menu items, labels, separators, and palette order
84
+ are outside manifest v1. They do not identify saved-project API references. Extension bundling
85
+ therefore continues to use `extensionBundles[].members` and runtime `getInfo().blocks` order; it does
86
+ not use manifest order to build the palette.
87
+
88
+ ## Compatibility policy
89
+
90
+ | Candidate change | Classification | Reason |
91
+ | ---------------------------- | -------------- | ---------------------------------------------------- |
92
+ | Add a block | Compatible | Existing saved blocks keep their handler |
93
+ | Add an unreferenced menu | Compatible | No existing argument contract changes |
94
+ | Remove an unreferenced menu | Compatible | No saved argument refers to the menu |
95
+ | Remove a block | Breaking | Saved opcodes lose their handler |
96
+ | Change a block type | Breaking | Saved block shape or evaluation changes |
97
+ | Add or remove an argument | Breaking | Manifest v1 cannot prove a safe default or migration |
98
+ | Change argument type or menu | Breaking | Saved input interpretation changes |
99
+ | Remove a referenced menu | Breaking | Existing menu references can no longer resolve |
100
+ | Change `acceptReporters` | Breaking | Accepted saved input shapes change |
101
+
102
+ Compatibility reports use stable paths such as:
103
+
104
+ ```text
105
+ /blocks/speak/blockType
106
+ /blocks/speak/arguments/VOICE/menu
107
+ /menus/voices/acceptReporters
108
+ ```
109
+
110
+ An ID migration explicitly normalizes the old and new top-level IDs before comparing the remaining
111
+ contract. Any other API difference follows the same policy.
112
+
113
+ If the remote manifest filename changes with the extension ID, supply the new path explicitly:
114
+
115
+ ```bash
116
+ sb3-toolchain extensions update app OLD_ID --migrate-id NEW_ID \
117
+ --artifact dist/newid.js \
118
+ --api-manifest-artifact dist/newid.manifest.json
119
+ ```
120
+
121
+ Both artifact paths and their integrity values are updated in the same transaction.
122
+
123
+ ## Status, sync, and update
124
+
125
+ `extensions status` validates both installed files offline when reporting `local=valid` or
126
+ `local=modified`. It resolves only the tracked Git ref and does not download a candidate manifest.
127
+
128
+ `extensions sync` downloads both artifacts from the recorded `resolvedCommit`. Both must match their
129
+ recorded integrity and IDs before either local file is replaced.
130
+
131
+ `extensions update` resolves `ref`, downloads both artifacts from the new commit, validates them, and
132
+ compares the candidate API with the installed manifest. New blocks are reported as compatible.
133
+ Breaking changes are rejected before a candidate directory is installed.
134
+
135
+ To apply an intentionally breaking update, review every reported path and use both explicit flags:
136
+
137
+ ```bash
138
+ sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
139
+ ```
140
+
141
+ `--allow-breaking-api` without `--yes` is rejected. This prevents an ordinary replacement
142
+ confirmation from also authorizing an API break.
143
+
144
+ The JavaScript, API manifest, `resolvedCommit`, and both integrity values are written in one
145
+ transaction. If one download or validation fails, expanded source is unchanged.
146
+
147
+ ## Check, build, and import
148
+
149
+ `check` and `build` verify the installed API manifest without network access. The manifest does not
150
+ enter `project.json` or the SB3 ZIP, so opting in does not change the generated SB3 bytes.
151
+
152
+ Re-importing an unchanged SB3 into an existing managed expanded source preserves both
153
+ `source.apiManifest` and its installed manifest file. A new import cannot infer GitHub provenance or
154
+ manifest metadata, so it does not enable the feature automatically. Existing manifest metadata is
155
+ read only for an extension with the same imported ID and path, and its local path is validated before
156
+ the manifest file is opened.
157
+
158
+ ## Rollback
159
+
160
+ For a project update, revert the project commit so that JavaScript, API manifest,
161
+ `resolvedCommit`, and both integrity values return together.
162
+
163
+ To stop API compatibility tracking without changing the embedded JavaScript:
164
+
165
+ 1. Remove `source.apiManifest` from the extension entry.
166
+ 2. Remove `extensions/<extensionId>.manifest.json`.
167
+ 3. Run `sb3-toolchain check` and rebuild the SB3.
168
+
169
+ The extension then follows the previous JavaScript provenance and integrity workflow.
@@ -46,12 +46,21 @@ upstream repository publishes an artifact declaring the new ID.
46
46
  ```bash
47
47
  sb3-toolchain extensions update app twOld \
48
48
  --migrate-id newext \
49
- --artifact dist/newext.js
49
+ --artifact dist/newext.js \
50
+ --api-manifest-artifact dist/newext.manifest.json
50
51
  ```
51
52
 
52
- Specify `--artifact` only when the upstream artifact path also changed. The tool resolves the tracked
53
- ref to an immutable commit and downloads the new artifact from that commit. It rejects an artifact
54
- that does not declare `// ID: newext`, a collision, or an invalid new ID before changing local files.
53
+ Specify `--artifact` only when the upstream JavaScript artifact path changed. Specify
54
+ `--api-manifest-artifact` only when an opt-in manifest artifact path also changed. The tool resolves
55
+ the tracked ref to an immutable commit and downloads the new artifacts from that commit. It rejects
56
+ an artifact that does not declare `// ID: newext`, a collision, or an invalid new ID before changing
57
+ local files.
58
+
59
+ If the managed extension has `source.apiManifest`, the tool downloads the candidate manifest from
60
+ the same commit, normalizes only the explicit old and new top-level IDs, and applies the ordinary API
61
+ compatibility policy to every remaining field. JavaScript, the renamed local manifest, provenance,
62
+ both remote artifact paths when supplied, and both integrity values change in one transaction. See
63
+ [`extension-api-compatibility.md`](extension-api-compatibility.md).
55
64
 
56
65
  ## Validation and rollback
57
66
 
@@ -0,0 +1,167 @@
1
+ # Extension API互換性マニフェスト
2
+
3
+ [English](../extension-api-compatibility.md)
4
+
5
+ 埋め込み機能拡張は、バージョン付きAPIマニフェストを任意で使用できます。これにより、
6
+ `sb3-toolchain`はJavaScriptを置き換える前に、保存済みプロジェクトとの契約を検査します。
7
+ マニフェストは検証用メタデータです。展開ソース内に保存され、JavaScriptと同じ変更不能なコミットから
8
+ 取得されますが、生成するSB3には埋め込まれません。
9
+
10
+ この機能は任意です。管理対象外の既存機能拡張と、`source.apiManifest`を持たない管理対象機能拡張は、
11
+ 従来の動作と決定的なSB3出力を維持します。
12
+
13
+ ## 2つ目の成果物が必要な理由
14
+
15
+ コミット固定とSHA-256によって、JavaScript成果物が真正かつ再現可能かを確認できます。しかし、更新後も、
16
+ 既存プロジェクトに保存されているopcodeや引数の形が提供されるかどうかは確認できません。
17
+
18
+ ```mermaid
19
+ flowchart LR
20
+ Ref["追跡対象のGit ref"] --> Commit["解決済みコミット"]
21
+ Commit --> JS["機能拡張JavaScript"]
22
+ Commit --> API["APIマニフェストv1"]
23
+ JS --> Identity["header ID + SHA-256"]
24
+ API --> Contract["opcode / 引数 / メニューの比較"]
25
+ Identity --> Candidate["検証済み候補"]
26
+ Contract --> Candidate
27
+ Candidate --> Transaction["1回のトランザクションによるソース更新"]
28
+ ```
29
+
30
+ マニフェストはJSONとして解析され、実行されることはありません。`sb3-toolchain`はcheckまたはbuildの
31
+ 実行時にスキーマを取得せず、マニフェストv1をローカルで検証します。
32
+
33
+ ## 展開ソースのメタデータ
34
+
35
+ 既存のGitHub `source`オブジェクトの下に`apiManifest`を追加します。
36
+
37
+ ```json
38
+ {
39
+ "id": "example",
40
+ "path": "extensions/example.js",
41
+ "mediaType": "text/javascript",
42
+ "parameters": [],
43
+ "encoding": "base64",
44
+ "source": {
45
+ "provider": "github",
46
+ "repository": "owner/example-extension",
47
+ "ref": "main",
48
+ "resolvedCommit": "0123456789abcdef0123456789abcdef01234567",
49
+ "artifact": "dist/example.js",
50
+ "integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
51
+ "apiManifest": {
52
+ "artifact": "dist/extension-manifest.json",
53
+ "path": "extensions/example.manifest.json",
54
+ "formatVersion": 1,
55
+ "integrity": "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="
56
+ }
57
+ }
58
+ }
59
+ ```
60
+
61
+ - `artifact`はGitHubリポジトリ内のマニフェストのパスです。
62
+ - `path`は展開ソース内の`extensions/<extensionId>.manifest.json`でなければなりません。
63
+ - `formatVersion`は`1`でなければなりません。
64
+ - `integrity`はインストール済みマニフェストファイルのSHA-256 SRI値です。
65
+
66
+ JavaScript成果物とマニフェスト成果物は、同じリポジトリと`resolvedCommit`を使用します。別のリポジトリや
67
+ コミットは、記録されたAPI契約を曖昧にするため、意図的にサポートしていません。
68
+
69
+ ## マニフェストv1の契約
70
+
71
+ マニフェストv1には次の情報が含まれます。
72
+
73
+ - 機能拡張ID
74
+ - ブロックのopcodeとブロック種別
75
+ - 引数のID、型、任意のメニュー参照
76
+ - メニューのIDと`acceptReporters`
77
+
78
+ 未知のプロパティ、識別子の重複、未知のメニュー参照、未対応バージョン、ID不一致は拒否されます。配列の順序は、
79
+ 比較前に正規化されます。
80
+
81
+ 表示テキスト、説明、デフォルト値、静的メニュー項目、`label`、`separator`、パレット順序はマニフェストv1の
82
+ 対象外です。これらは保存済みプロジェクトのAPI参照を識別するものではありません。そのため、機能拡張の
83
+ bundleでは、引き続き`extensionBundles[].members`と実行時の`getInfo().blocks`の順序を使用します。
84
+ パレット構築にマニフェストの順序は使用しません。
85
+
86
+ ## 互換性ポリシー
87
+
88
+ | 候補の変更 | 分類 | 理由 |
89
+ | ------------------------ | ---------- | ------------------------------------------------------ |
90
+ | ブロックを追加 | Compatible | 既存の保存済みブロックは処理を維持する |
91
+ | 未参照メニューを追加 | Compatible | 既存の引数契約は変わらない |
92
+ | 未参照メニューを削除 | Compatible | 保存済み引数から参照されていない |
93
+ | ブロックを削除 | Breaking | 保存済みopcodeの処理が失われる |
94
+ | ブロック種別を変更 | Breaking | 保存済みブロックの形または評価方法が変わる |
95
+ | 引数を追加または削除 | Breaking | マニフェストv1では安全なデフォルトや移行を証明できない |
96
+ | 引数の型やメニューを変更 | Breaking | 保存済み入力の解釈が変わる |
97
+ | 参照中メニューを削除 | Breaking | 既存のメニュー参照を解決できなくなる |
98
+ | `acceptReporters`を変更 | Breaking | 受け入れ可能な保存済み入力の形が変わる |
99
+
100
+ 互換性レポートでは、次のような安定したパスを使用します。
101
+
102
+ ```text
103
+ /blocks/speak/blockType
104
+ /blocks/speak/arguments/VOICE/menu
105
+ /menus/voices/acceptReporters
106
+ ```
107
+
108
+ ID移行では、明示された旧IDと新IDのトップレベルIDだけを正規化してから、残りの契約を比較します。それ以外の
109
+ API差分には、同じ互換性ポリシーを適用します。
110
+
111
+ リモートのマニフェストファイル名も機能拡張IDとともに変わる場合は、新しいパスを明示します。
112
+
113
+ ```bash
114
+ sb3-toolchain extensions update app OLD_ID --migrate-id NEW_ID \
115
+ --artifact dist/newid.js \
116
+ --api-manifest-artifact dist/newid.manifest.json
117
+ ```
118
+
119
+ 2つの成果物パスとintegrity値は、同じトランザクションで更新されます。
120
+
121
+ ## Status、sync、update
122
+
123
+ `extensions status`は、`local=valid`または`local=modified`を報告するとき、インストール済みの2つの
124
+ ファイルをオフラインで検証します。追跡対象のGit refだけを解決し、候補マニフェストはダウンロードしません。
125
+
126
+ `extensions sync`は、記録済みの`resolvedCommit`から2つの成果物をダウンロードします。ローカルファイルを
127
+ 置き換える前に、両方のIDと記録済みintegrityが一致しなければなりません。
128
+
129
+ `extensions update`は`ref`を解決し、新しいコミットから両方の成果物をダウンロードして検証した後、候補APIと
130
+ インストール済みマニフェストを比較します。新しいブロックはCompatibleとして報告されます。Breakingに分類される
131
+ 変更がある場合、候補ディレクトリをインストールする前に拒否します。
132
+
133
+ 意図的に破壊的更新を適用する場合は、報告されたすべてのパスを確認し、次の2つの明示的なフラグを使用します。
134
+
135
+ ```bash
136
+ sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
137
+ ```
138
+
139
+ `--yes`を伴わない`--allow-breaking-api`は拒否されます。これにより、通常の置換確認がAPI破壊の許可を
140
+ 兼ねてしまうことを防ぎます。
141
+
142
+ JavaScript、APIマニフェスト、`resolvedCommit`、2つのintegrity値は、1回のトランザクションで書き込まれます。
143
+ ダウンロードまたは検証のいずれかが失敗した場合、展開ソースは変更されません。
144
+
145
+ ## Check、build、import
146
+
147
+ `check`と`build`は、ネットワークへ接続せずにインストール済みAPIマニフェストを検証します。マニフェストは
148
+ `project.json`やSB3 ZIPへ追加されないため、この機能を有効にしても生成されるSB3のバイト列は変わりません。
149
+
150
+ 変更されていないSB3を既存の管理対象展開ソースへ再インポートすると、`source.apiManifest`とインストール済み
151
+ マニフェストファイルの両方が保持されます。新規インポートではGitHubの来歴やマニフェストメタデータを
152
+ 推測できないため、この機能を自動的に有効にはしません。既存のマニフェストメタデータを読み込むのは、
153
+ インポートしたIDとパスが一致する機能拡張だけです。また、マニフェストファイルを開く前にローカルパスを
154
+ 検証します。
155
+
156
+ ## ロールバック
157
+
158
+ プロジェクトを更新した場合は、プロジェクトのコミットをrevertし、JavaScript、APIマニフェスト、
159
+ `resolvedCommit`、2つのintegrity値をまとめて元に戻します。
160
+
161
+ 埋め込みJavaScriptを変更せずにAPI互換性の追跡を停止するには、次の手順を実行します。
162
+
163
+ 1. 機能拡張エントリから`source.apiManifest`を削除します。
164
+ 2. `extensions/<extensionId>.manifest.json`を削除します。
165
+ 3. `sb3-toolchain check`を実行し、SB3を再ビルドします。
166
+
167
+ その後、機能拡張は従来のJavaScript来歴とintegrityのワークフローに戻ります。
@@ -60,7 +60,13 @@ metadata can be added for an extension managed from GitHub.
60
60
  "ref": "main",
61
61
  "resolvedCommit": "0123456789abcdef0123456789abcdef01234567",
62
62
  "artifact": "dist/example.js",
63
- "integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
63
+ "integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
64
+ "apiManifest": {
65
+ "artifact": "dist/extension-manifest.json",
66
+ "path": "extensions/example.manifest.json",
67
+ "formatVersion": 1,
68
+ "integrity": "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="
69
+ }
64
70
  }
65
71
  }
66
72
  ]
@@ -72,28 +78,43 @@ metadata can be added for an extension managed from GitHub.
72
78
  - `resolvedCommit`: lowercase 40-character commit SHA used to obtain the current file
73
79
  - `artifact`: JavaScript artifact path relative to the repository root
74
80
  - `integrity`: SRI-form SHA-256 of the current file
81
+ - `apiManifest`: optional, opt-in API compatibility metadata
82
+ - `artifact`: API manifest path relative to the same GitHub repository
83
+ - `path`: required local path `extensions/<extensionId>.manifest.json`
84
+ - `formatVersion`: supported manifest format, currently `1`
85
+ - `integrity`: SRI-form SHA-256 of the installed manifest
75
86
 
76
87
  Validation and builds verify managed extensions without accessing the network:
77
88
 
78
89
  - The actual file SHA-256 matches `integrity`
79
90
  - The file's `// ID: <extensionId>` header matches `id`
80
91
  - The repository, ref, commit, and artifact path use safe forms
92
+ - When `apiManifest` exists, its JSON schema, ID, format version, path, and SHA-256 are valid
81
93
 
82
94
  Re-importing an SB3 into an existing expanded source directory preserves `source` metadata for the
83
95
  same ID and path. If the imported file does not match the recorded hash or ID, the import is rejected
84
96
  without changing the existing output. A new import cannot infer provenance, so it does not create
85
97
  `source` automatically.
86
98
 
87
- `extensions sync` downloads `artifact` using the immutable `resolvedCommit` and restores the local
88
- file only when the downloaded ID and hash match the existing metadata. `extensions update` resolves
89
- `ref` through the GitHub API and updates `resolvedCommit` and `integrity` to match the artifact from
90
- that commit. The expanded source is not changed until every selected entry has been downloaded and
91
- validated successfully.
99
+ `extensions sync` downloads the JavaScript and optional API manifest using the immutable
100
+ `resolvedCommit` and restores local files only when their IDs and hashes match the existing metadata.
101
+ `extensions update` resolves `ref` through the GitHub API, downloads both artifacts from that same
102
+ commit, and compares a candidate API manifest with the installed contract. It updates
103
+ `resolvedCommit` and both integrity values only after compatibility and content validation succeed.
104
+ The expanded source is not changed until every selected entry has been downloaded and validated.
92
105
 
93
106
  An extension ID migration changes the manifest `id` and `path`, known references in
94
107
  `project.source.json`, and `extensions/<id>.js` in one transaction. When a managed extension is
95
108
  migrated as part of `extensions update`, `artifact` when explicitly supplied, `resolvedCommit`, and
96
- `integrity` are also updated for the new artifact.
109
+ `integrity` are also updated for the new artifact. An opt-in API manifest is compared after
110
+ normalizing the explicit old and new top-level IDs, saved under the new ID, and updated in the same
111
+ transaction. If its remote filename also changes, `--api-manifest-artifact` updates
112
+ `source.apiManifest.artifact` explicitly.
113
+
114
+ API manifest files are expanded-source validation inputs, not SB3 archive entries. They do not
115
+ change deterministic SB3 bytes. See
116
+ [`extension-api-compatibility.md`](extension-api-compatibility.md) for manifest v1, compatibility
117
+ classification, the explicit breaking-change override, and rollback.
97
118
 
98
119
  ### `extensionBundles`
99
120
 
package/docs/workflows.md CHANGED
@@ -87,8 +87,8 @@ operations, images, sounds, and embedded extension behavior.
87
87
  ## Managed embedded extensions
88
88
 
89
89
  The `source` object in `embedded-extensions.json` can record the GitHub repository, tracked ref,
90
- resolved commit, artifact path, and SHA-256. See [`source-format-v1.md`](source-format-v1.md) for the
91
- complete schema.
90
+ resolved commit, artifact path, and SHA-256. It can also opt in to a versioned API manifest for static
91
+ update compatibility checks. See [`source-format-v1.md`](source-format-v1.md) for the complete schema.
92
92
 
93
93
  The extension commands have the following roles:
94
94
 
@@ -118,7 +118,8 @@ sb3-toolchain check app
118
118
  ```
119
119
 
120
120
  `sync` does not resolve a mutable branch or tag. It downloads from the recorded `resolvedCommit` and
121
- replaces a local file only when the artifact ID and SHA-256 match the recorded metadata.
121
+ replaces local files only when JavaScript and an optional API manifest match their recorded IDs and
122
+ SHA-256 values.
122
123
 
123
124
  ### Update a tracked ref
124
125
 
@@ -132,8 +133,21 @@ git diff -- app
132
133
  Omitting the ID updates all managed extensions as one transaction. If any download or validation
133
134
  fails, neither files nor metadata are changed.
134
135
 
135
- In an update PR, review `resolvedCommit`, `integrity`, and the JavaScript artifact together, then test
136
- the extension's primary features in the generated SB3.
136
+ When `source.apiManifest` is present, the update downloads JavaScript and the API manifest from the
137
+ same resolved commit. Compatible additions are reported. A removed block, changed block type,
138
+ argument-contract change, removed referenced menu, or `acceptReporters` change is rejected before
139
+ installation. Removing an unreferenced menu is compatible. After reviewing every reported path, an
140
+ intentionally breaking update requires both flags:
141
+
142
+ ```bash
143
+ sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
144
+ ```
145
+
146
+ See [`extension-api-compatibility.md`](extension-api-compatibility.md) for the versioned manifest
147
+ contract, classification table, default-off behavior, and rollback.
148
+
149
+ In an update PR, review `resolvedCommit`, JavaScript and manifest integrity, compatibility paths, and
150
+ both artifacts together, then test the extension's primary features in the generated SB3.
137
151
 
138
152
  ## Migrate an extension ID
139
153
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/sb3-toolchain",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Git-friendly source management and deterministic builds for Scratch 3 and TurboWarp SB3 projects",
5
5
  "type": "module",
6
6
  "license": "MPL-2.0",
package/src/cli.js CHANGED
@@ -26,7 +26,7 @@ export function usage() {
26
26
  sb3-toolchain build SOURCE_DIR --output OUTPUT.sb3 [--yes]
27
27
  sb3-toolchain extensions status SOURCE_DIR
28
28
  sb3-toolchain extensions sync SOURCE_DIR [--yes]
29
- sb3-toolchain extensions update SOURCE_DIR [EXTENSION_ID] [--migrate-id NEW_ID] [--artifact PATH] [--yes]
29
+ sb3-toolchain extensions update SOURCE_DIR [EXTENSION_ID] [--migrate-id NEW_ID] [--artifact PATH] [--api-manifest-artifact PATH] [--allow-breaking-api --yes]
30
30
  sb3-toolchain extensions migrate-id SOURCE_DIR --from OLD_ID --to NEW_ID [--yes]
31
31
  sb3-toolchain extensions bundle SOURCE_DIR --id BUNDLE_ID --name NAME [EXTENSION_ID ...] [--yes]
32
32
  sb3-toolchain extensions unbundle SOURCE_DIR BUNDLE_ID [--yes]
@@ -115,6 +115,8 @@ function parseBuildArguments(arguments_) {
115
115
  }
116
116
 
117
117
  function parseExtensionMutationArguments(action, arguments_) {
118
+ let allowBreakingApi = false;
119
+ let apiManifestArtifact;
118
120
  let sourceDirectory;
119
121
  let extensionId;
120
122
  let migrateToId;
@@ -125,6 +127,9 @@ function parseExtensionMutationArguments(action, arguments_) {
125
127
  const argument = arguments_[index];
126
128
  if (argument === '--yes') {
127
129
  yes = true;
130
+ } else if (argument === '--allow-breaking-api') {
131
+ assert(action === 'update', '--allow-breaking-api is only valid for extensions update.');
132
+ allowBreakingApi = true;
128
133
  } else if (argument === '--migrate-id') {
129
134
  assert(action === 'update', '--migrate-id is only valid for extensions update.');
130
135
  migrateToId = takeValue(arguments_, index, '--migrate-id');
@@ -133,6 +138,10 @@ function parseExtensionMutationArguments(action, arguments_) {
133
138
  assert(action === 'update', '--artifact is only valid for extensions update.');
134
139
  sourceArtifact = takeValue(arguments_, index, '--artifact');
135
140
  index += 1;
141
+ } else if (argument === '--api-manifest-artifact') {
142
+ assert(action === 'update', '--api-manifest-artifact is only valid for extensions update.');
143
+ apiManifestArtifact = takeValue(arguments_, index, '--api-manifest-artifact');
144
+ index += 1;
136
145
  } else {
137
146
  assert(!argument.startsWith('-'), `Unknown option: ${argument}`);
138
147
  if (!sourceDirectory) {
@@ -158,8 +167,15 @@ function parseExtensionMutationArguments(action, arguments_) {
158
167
  sourceArtifact === undefined || migrateToId !== undefined,
159
168
  '--artifact requires --migrate-id.',
160
169
  );
170
+ assert(
171
+ apiManifestArtifact === undefined || migrateToId !== undefined,
172
+ '--api-manifest-artifact requires --migrate-id.',
173
+ );
174
+ assert(!allowBreakingApi || yes, '--allow-breaking-api requires --yes.');
161
175
  return {
162
176
  action,
177
+ ...(allowBreakingApi ? {allowBreakingApi} : {}),
178
+ ...(apiManifestArtifact ? {apiManifestArtifact} : {}),
163
179
  command: 'extensions',
164
180
  extensionId,
165
181
  migrateToId,
@@ -561,6 +577,8 @@ export async function runCli(
561
577
  ? await syncExtensions(operationOptions)
562
578
  : await updateExtensions({
563
579
  ...operationOptions,
580
+ allowBreakingApi: options.allowBreakingApi,
581
+ apiManifestArtifact: options.apiManifestArtifact,
564
582
  extensionId: options.extensionId,
565
583
  migrateToId: options.migrateToId,
566
584
  sourceArtifact: options.sourceArtifact,
@@ -580,6 +598,14 @@ export async function runCli(
580
598
  log,
581
599
  );
582
600
  }
601
+ for (const compatibility of result.apiCompatibility) {
602
+ for (const change of compatibility.changes) {
603
+ log(
604
+ `API ${compatibility.id}: ${change.breaking ? 'breaking' : 'compatible'} ` +
605
+ `${change.kind} ${change.path}`,
606
+ );
607
+ }
608
+ }
583
609
  if (result.rollbackCleanupWarning) log(result.rollbackCleanupWarning);
584
610
  return;
585
611
  }
package/src/constants.js CHANGED
@@ -1,4 +1,4 @@
1
1
  // SPDX-License-Identifier: MPL-2.0
2
2
 
3
3
  export const packageName = '@kubohiroya/sb3-toolchain';
4
- export const packageVersion = '0.2.0';
4
+ export const packageVersion = '0.3.0';