@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 +6 -1
- package/docs/extension-api-compatibility.md +169 -0
- package/docs/extension-id-migration.md +13 -4
- package/docs/ja/extension-api-compatibility.md +167 -0
- package/docs/source-format-v1.md +28 -7
- package/docs/workflows.md +19 -5
- package/package.json +1 -1
- package/src/cli.js +27 -1
- package/src/constants.js +1 -1
- package/src/extension-api-manifest.js +336 -0
- package/src/extension-dependencies.js +2 -0
- package/src/extension-id-migration.js +74 -3
- package/src/extension-sync.js +189 -20
- package/src/import.js +28 -12
- package/src/index.js +11 -0
- package/src/source.js +15 -0
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.
|
|
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
|
|
53
|
-
|
|
54
|
-
|
|
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のワークフローに戻ります。
|
package/docs/source-format-v1.md
CHANGED
|
@@ -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
|
|
88
|
-
|
|
89
|
-
`ref` through the GitHub API
|
|
90
|
-
|
|
91
|
-
|
|
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.
|
|
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
|
|
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
|
-
|
|
136
|
-
|
|
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
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