@kubohiroya/sb3-toolchain 0.1.1 → 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 +59 -96
- package/docs/extension-api-compatibility.md +169 -0
- package/docs/extension-bundles.md +446 -0
- package/docs/extension-id-migration.md +44 -33
- package/docs/ja/extension-api-compatibility.md +167 -0
- package/docs/source-format-v1.md +134 -62
- package/docs/workflows.md +249 -0
- package/package.json +1 -1
- package/src/build.js +21 -7
- package/src/cli.js +176 -3
- package/src/constants.js +1 -1
- package/src/extension-api-manifest.js +336 -0
- package/src/extension-bundle-archive.js +422 -0
- package/src/extension-bundle-configuration.js +247 -0
- package/src/extension-bundle.js +640 -0
- package/src/extension-dependencies.js +16 -1
- 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 +25 -0
- package/src/source.js +48 -7
|
@@ -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
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# SB3
|
|
1
|
+
# SB3 expanded source format v1
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## Layout
|
|
4
4
|
|
|
5
5
|
```text
|
|
6
6
|
SOURCE_DIR/
|
|
@@ -13,7 +13,8 @@ SOURCE_DIR/
|
|
|
13
13
|
└── <extensionId>.js
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
`sb3-source.json
|
|
16
|
+
`sb3-source.json` records the format version, paths to each component, and the ZIP entry order of the
|
|
17
|
+
original SB3.
|
|
17
18
|
|
|
18
19
|
```json
|
|
19
20
|
{
|
|
@@ -27,21 +28,21 @@ SOURCE_DIR/
|
|
|
27
28
|
|
|
28
29
|
## `project.source.json`
|
|
29
30
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
31
|
+
This file is the original SB3 `project.json` formatted as two-space-indented JSON. Array and object
|
|
32
|
+
order are preserved as meaningful input. A TurboWarp extension that was embedded as a data URL is
|
|
33
|
+
replaced by this reference:
|
|
33
34
|
|
|
34
35
|
```text
|
|
35
36
|
embedded-extension:extensions/<extensionId>.js
|
|
36
37
|
```
|
|
37
38
|
|
|
38
|
-
|
|
39
|
-
|
|
39
|
+
During a build, the media type, parameters, and encoding from `embedded-extensions.json` are used to
|
|
40
|
+
reconstruct the data URL.
|
|
40
41
|
|
|
41
42
|
## `embedded-extensions.json`
|
|
42
43
|
|
|
43
|
-
|
|
44
|
-
|
|
44
|
+
This file records embedded extension data URL information and extraction paths. Optional `source`
|
|
45
|
+
metadata can be added for an extension managed from GitHub.
|
|
45
46
|
|
|
46
47
|
```json
|
|
47
48
|
{
|
|
@@ -59,61 +60,132 @@ embedded-extension:extensions/<extensionId>.js
|
|
|
59
60
|
"ref": "main",
|
|
60
61
|
"resolvedCommit": "0123456789abcdef0123456789abcdef01234567",
|
|
61
62
|
"artifact": "dist/example.js",
|
|
62
|
-
"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
|
+
}
|
|
63
70
|
}
|
|
64
71
|
}
|
|
65
72
|
]
|
|
66
73
|
}
|
|
67
74
|
```
|
|
68
75
|
|
|
69
|
-
- `repository`: `<owner>/<repository
|
|
70
|
-
- `ref`:
|
|
71
|
-
- `resolvedCommit`:
|
|
72
|
-
- `artifact`:
|
|
73
|
-
- `integrity`:
|
|
74
|
-
|
|
75
|
-
`
|
|
76
|
-
|
|
77
|
-
-
|
|
78
|
-
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
`
|
|
86
|
-
|
|
87
|
-
`
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
`extensions
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
76
|
+
- `repository`: GitHub repository in `<owner>/<repository>` form
|
|
77
|
+
- `ref`: branch, tag, or commit to track for update candidates
|
|
78
|
+
- `resolvedCommit`: lowercase 40-character commit SHA used to obtain the current file
|
|
79
|
+
- `artifact`: JavaScript artifact path relative to the repository root
|
|
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
|
|
86
|
+
|
|
87
|
+
Validation and builds verify managed extensions without accessing the network:
|
|
88
|
+
|
|
89
|
+
- The actual file SHA-256 matches `integrity`
|
|
90
|
+
- The file's `// ID: <extensionId>` header matches `id`
|
|
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
|
|
93
|
+
|
|
94
|
+
Re-importing an SB3 into an existing expanded source directory preserves `source` metadata for the
|
|
95
|
+
same ID and path. If the imported file does not match the recorded hash or ID, the import is rejected
|
|
96
|
+
without changing the existing output. A new import cannot infer provenance, so it does not create
|
|
97
|
+
`source` automatically.
|
|
98
|
+
|
|
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.
|
|
105
|
+
|
|
106
|
+
An extension ID migration changes the manifest `id` and `path`, known references in
|
|
107
|
+
`project.source.json`, and `extensions/<id>.js` in one transaction. When a managed extension is
|
|
108
|
+
migrated as part of `extensions update`, `artifact` when explicitly supplied, `resolvedCommit`, and
|
|
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.
|
|
118
|
+
|
|
119
|
+
### `extensionBundles`
|
|
120
|
+
|
|
121
|
+
Add the optional `extensionBundles` array to make multiple individual extensions one permission unit
|
|
122
|
+
only in the generated SB3.
|
|
123
|
+
|
|
124
|
+
```json
|
|
125
|
+
{
|
|
126
|
+
"formatVersion": 1,
|
|
127
|
+
"extensions": [
|
|
128
|
+
{
|
|
129
|
+
"id": "extensionone",
|
|
130
|
+
"path": "extensions/extensionone.js",
|
|
131
|
+
"mediaType": "text/javascript",
|
|
132
|
+
"parameters": [],
|
|
133
|
+
"encoding": "base64"
|
|
134
|
+
},
|
|
135
|
+
{
|
|
136
|
+
"id": "extensiontwo",
|
|
137
|
+
"path": "extensions/extensiontwo.js",
|
|
138
|
+
"mediaType": "text/javascript",
|
|
139
|
+
"parameters": [],
|
|
140
|
+
"encoding": "base64"
|
|
141
|
+
}
|
|
142
|
+
],
|
|
143
|
+
"extensionBundles": [
|
|
144
|
+
{
|
|
145
|
+
"id": "projectbundle",
|
|
146
|
+
"name": "Project Extension Bundle",
|
|
147
|
+
"members": ["extensionone", "extensiontwo"]
|
|
148
|
+
}
|
|
149
|
+
]
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
- `id`: composite extension ID in TurboWarp's `[a-z0-9]+` form that does not collide with an individual extension
|
|
154
|
+
- `name`: single-line name displayed in the permission prompt and extension category
|
|
155
|
+
- `members`: two or more individual extension IDs; their order defines block and menu composition order. The palette receives a decorated, metadata-bearing bundle LABEL heading and a double separator between groups, while LABEL entries and separators from the original extensions remain unchanged
|
|
156
|
+
|
|
157
|
+
A member cannot belong to more than one bundle. Individual entries, individual JavaScript, `source`,
|
|
158
|
+
and `project.source.json` remain authoritative. `build` adds `memberId + "__"` to each original opcode
|
|
159
|
+
and changes only the output `project.json` opcodes, `extensions`, `extensionURLs`, and extension storage
|
|
160
|
+
to the bundle ID. It embeds one bundle JavaScript data URL.
|
|
161
|
+
|
|
162
|
+
The end of the bundle JavaScript contains a format 1 recovery capsule with the original individual
|
|
163
|
+
data URLs and extension order. Removing the configuration or running `extensions unbundle` against a
|
|
164
|
+
generated SB3 containing that capsule restores the ordinary output. See
|
|
165
|
+
[`extension-bundles.md`](extension-bundles.md) for the compatibility contract and restoration steps.
|
|
166
|
+
|
|
167
|
+
## Assets
|
|
168
|
+
|
|
169
|
+
`assets/` contains costumes and sounds referenced by `project.source.json`. Each filename is
|
|
170
|
+
`<assetId>.<dataFormat>`, and `assetId` must match the MD5 of its contents. An unreferenced, missing,
|
|
171
|
+
or extra file is a validation error.
|
|
172
|
+
|
|
173
|
+
## Deterministic output
|
|
174
|
+
|
|
175
|
+
- ZIP entries follow `archiveEntries`
|
|
176
|
+
- ZIP timestamps are fixed at 1980-01-01 00:00:00
|
|
177
|
+
- Compression level is fixed at 6
|
|
178
|
+
- `project.json` is stored as minimal JSON with a trailing newline
|
|
179
|
+
- The same source format version, input files, and tool version produce the same byte sequence
|
|
180
|
+
|
|
181
|
+
## Safety
|
|
182
|
+
|
|
183
|
+
- Reject ZIP entries containing absolute paths, `\`, empty components, `.`, or `..`
|
|
184
|
+
- Reject symbolic links and special files as source input
|
|
185
|
+
- Reject a filesystem root, Git repository root, its ancestor, or `.git/` as an import destination
|
|
186
|
+
- Never overwrite an unrecognized existing directory
|
|
187
|
+
- Never discard Git-managed changes without the explicit two-stage override
|
|
188
|
+
- Never overwrite automatically when an interrupted replacement rollback area is present
|
|
189
|
+
- Verify managed extensions offline against their commit, SHA-256, and extension ID
|
|
190
|
+
- Preserve individual JavaScript and provenance during bundling and reject contracts whose compatibility cannot be established
|
|
191
|
+
- Fetch from GitHub only over HTTPS with redirects rejected and a size limit, and never execute downloaded JavaScript
|
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
# SB3 source-management workflows
|
|
2
|
+
|
|
3
|
+
This document describes the common workflow for managing a Scratch 3 or TurboWarp SB3 as expanded
|
|
4
|
+
source in Git and rebuilding a validated SB3. Each project repository should define its own editing,
|
|
5
|
+
testing, and distribution procedures.
|
|
6
|
+
|
|
7
|
+
See [`source-format-v1.md`](source-format-v1.md) for the expanded directory layout and file formats.
|
|
8
|
+
|
|
9
|
+
## Principles
|
|
10
|
+
|
|
11
|
+
- Treat the expanded directory in Git as the source of truth and generated SB3 files as build artifacts
|
|
12
|
+
- Import an SB3 edited in the TurboWarp Editor only after reviewing its differences
|
|
13
|
+
- Run `check` before committing and before distribution
|
|
14
|
+
- Build in CI and release workflows from a pinned toolchain version and committed expanded source
|
|
15
|
+
- Reproduce managed embedded extensions from a pinned source commit and SHA-256
|
|
16
|
+
|
|
17
|
+
The examples below use `app/` for the expanded source, `tmp/edited.sb3` for an SB3 saved by the
|
|
18
|
+
editor, and `dist/project.sb3` for generated output. Choose project-specific paths as needed.
|
|
19
|
+
|
|
20
|
+
## Initial import
|
|
21
|
+
|
|
22
|
+
Expand an SB3 saved by TurboWarp into files suitable for Git.
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
sb3-toolchain import tmp/edited.sb3 --output app
|
|
26
|
+
sb3-toolchain check app
|
|
27
|
+
git status --short
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
After import, verify at least the following:
|
|
31
|
+
|
|
32
|
+
- Changes in `project.source.json` correspond to operations performed in the editor
|
|
33
|
+
- Only intended assets were added to or removed from `assets/`
|
|
34
|
+
- `extensions/` and `embedded-extensions.json` contain no unexpected changes
|
|
35
|
+
- `sb3-toolchain check app` succeeds
|
|
36
|
+
|
|
37
|
+
A new import does not infer where embedded JavaScript came from. Add the provenance metadata described
|
|
38
|
+
below when an extension hosted on GitHub should become managed.
|
|
39
|
+
|
|
40
|
+
## Re-import into existing source
|
|
41
|
+
|
|
42
|
+
After editing the project, import the saved SB3 into the existing expanded source directory.
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
git status --short
|
|
46
|
+
sb3-toolchain import tmp/edited.sb3 --output app
|
|
47
|
+
sb3-toolchain check app
|
|
48
|
+
git diff -- app
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The tool asks for replacement confirmation when the existing expanded source differs. In a
|
|
52
|
+
non-interactive environment, `--yes` skips that confirmation but does not discard uncommitted
|
|
53
|
+
Git-managed changes. Specify both options only after reviewing the changes that will be discarded.
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
sb3-toolchain import tmp/edited.sb3 --output app \
|
|
57
|
+
--yes \
|
|
58
|
+
--discard-local-changes
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`--discard-local-changes` is not a recovery mechanism. Commit or otherwise preserve required changes
|
|
62
|
+
before using it. There is no `--force` option.
|
|
63
|
+
|
|
64
|
+
Provenance metadata for a managed extension with the same ID and path is preserved during re-import.
|
|
65
|
+
If the JavaScript in the SB3 differs from the recorded ID or SHA-256, the import is rejected without
|
|
66
|
+
changing the existing output, preventing provenance from becoming inconsistent with the actual file.
|
|
67
|
+
|
|
68
|
+
## Validation and build
|
|
69
|
+
|
|
70
|
+
Use `check` to validate only the expanded source and `build` to generate an SB3.
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
sb3-toolchain check app
|
|
74
|
+
sb3-toolchain build app --output dist/project.sb3
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`check` and `build` do not access the network. They validate asset references, MD5 hashes, the
|
|
78
|
+
expanded format, embedded extension IDs, and SHA-256 hashes using only local inputs.
|
|
79
|
+
|
|
80
|
+
`build` fixes the ZIP entry order, timestamps, and compression settings. The same toolchain version
|
|
81
|
+
and expanded source produce a bit-for-bit identical SB3. An identical existing output is left
|
|
82
|
+
untouched. A differing output requires replacement confirmation or `--yes`.
|
|
83
|
+
|
|
84
|
+
In addition to project-specific tests, open the generated SB3 in TurboWarp and verify startup, primary
|
|
85
|
+
operations, images, sounds, and embedded extension behavior.
|
|
86
|
+
|
|
87
|
+
## Managed embedded extensions
|
|
88
|
+
|
|
89
|
+
The `source` object in `embedded-extensions.json` can record the GitHub repository, tracked ref,
|
|
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
|
+
|
|
93
|
+
The extension commands have the following roles:
|
|
94
|
+
|
|
95
|
+
| Command | Network | Resolve ref | Metadata update | Purpose |
|
|
96
|
+
| ----------------------- | ------- | ----------- | --------------- | ------------------------------------------- |
|
|
97
|
+
| `extensions status` | Yes | Yes | No | Check whether a tracked ref has an update |
|
|
98
|
+
| `extensions sync` | Yes | No | No | Restore files from the pinned commit |
|
|
99
|
+
| `extensions update` | Yes | Yes | Yes | Explicitly update to the latest ref commit |
|
|
100
|
+
| `extensions migrate-id` | No | No | IDs/references | Migrate an extension ID used by the project |
|
|
101
|
+
| `extensions bundle` | No | No | Bundle config | Combine extensions into one permission unit |
|
|
102
|
+
| `extensions unbundle` | No | No | Config or SB3 | Restore output with individual extensions |
|
|
103
|
+
|
|
104
|
+
### Check for updates
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
sb3-toolchain extensions status app
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
`status` does not change local files. Review upstream changes for extensions whose tracked ref differs
|
|
111
|
+
from `resolvedCommit`, then decide whether to update.
|
|
112
|
+
|
|
113
|
+
### Restore from a pinned commit
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
sb3-toolchain extensions sync app
|
|
117
|
+
sb3-toolchain check app
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
`sync` does not resolve a mutable branch or tag. It downloads from the recorded `resolvedCommit` and
|
|
121
|
+
replaces local files only when JavaScript and an optional API manifest match their recorded IDs and
|
|
122
|
+
SHA-256 values.
|
|
123
|
+
|
|
124
|
+
### Update a tracked ref
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
sb3-toolchain extensions update app
|
|
128
|
+
sb3-toolchain extensions update app EXTENSION_ID
|
|
129
|
+
sb3-toolchain check app
|
|
130
|
+
git diff -- app
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Omitting the ID updates all managed extensions as one transaction. If any download or validation
|
|
134
|
+
fails, neither files nor metadata are changed.
|
|
135
|
+
|
|
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.
|
|
151
|
+
|
|
152
|
+
## Migrate an extension ID
|
|
153
|
+
|
|
154
|
+
An extension ID is stored in opcodes and monitors, so do not change only its filename or manifest by
|
|
155
|
+
hand. Start with a dry run and inspect both classified and unclassified references.
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Prepare JavaScript declaring the new ID, review the result, and then apply it.
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID --yes
|
|
165
|
+
sb3-toolchain check app
|
|
166
|
+
git diff -- app
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
For a GitHub-managed extension, the upstream artifact update and ID migration can be one transaction.
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
sb3-toolchain extensions update app OLD_ID \
|
|
173
|
+
--migrate-id NEW_ID \
|
|
174
|
+
--artifact dist/NEW_ID.js
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Specify `--artifact` only when the upstream artifact path also changed. See
|
|
178
|
+
[`extension-id-migration.md`](extension-id-migration.md) for the affected schema, collision checks,
|
|
179
|
+
unclassified references, and rollback details.
|
|
180
|
+
|
|
181
|
+
## Combine unsandboxed permission into one prompt
|
|
182
|
+
|
|
183
|
+
A project containing several embedded extensions can opt in to a static bundle. Original JavaScript,
|
|
184
|
+
IDs, opcodes, and provenance remain unchanged; only build output is transformed into one composite
|
|
185
|
+
extension.
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
sb3-toolchain extensions bundle app \
|
|
189
|
+
--id projectbundle \
|
|
190
|
+
--name "Project Extension Bundle" \
|
|
191
|
+
extensionone extensiontwo
|
|
192
|
+
sb3-toolchain extensions bundle app \
|
|
193
|
+
--id projectbundle \
|
|
194
|
+
--name "Project Extension Bundle" \
|
|
195
|
+
extensionone extensiontwo \
|
|
196
|
+
--yes
|
|
197
|
+
sb3-toolchain check app
|
|
198
|
+
sb3-toolchain build app --output dist/project.sb3 --yes
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Use project-level automated tests and a real TurboWarp smoke test to verify equivalent behavior before
|
|
202
|
+
and after bundling, a single permission prompt, and successful reload after saving. If there is a
|
|
203
|
+
problem, restore the preserved individual extensions.
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
sb3-toolchain extensions unbundle app projectbundle
|
|
207
|
+
sb3-toolchain extensions unbundle app projectbundle --yes
|
|
208
|
+
sb3-toolchain check app
|
|
209
|
+
sb3-toolchain build app --output dist/project.sb3 --yes
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
An SB3 generated by this version of the toolchain can also be unbundled directly when the expanded
|
|
213
|
+
source is unavailable. The first command is a dry run; output is written only with `--yes`.
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
sb3-toolchain extensions unbundle \
|
|
217
|
+
dist/project.sb3 projectbundle \
|
|
218
|
+
--output dist/project.unbundled.sb3
|
|
219
|
+
sb3-toolchain extensions unbundle \
|
|
220
|
+
dist/project.sb3 projectbundle \
|
|
221
|
+
--output dist/project.unbundled.sb3 \
|
|
222
|
+
--yes
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
See [`extension-bundles.md`](extension-bundles.md) for the compatibility contract, source comments,
|
|
226
|
+
opcode and storage transformations, direct-unbundle limitations, and re-import precautions.
|
|
227
|
+
|
|
228
|
+
## CI and distribution
|
|
229
|
+
|
|
230
|
+
Pin dependency versions and run at least the following in CI:
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
sb3-toolchain check app
|
|
234
|
+
sb3-toolchain build app --output dist/project.sb3 --yes
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
Distribute only an SB3 that passed project-level automated tests and manual verification. Do not
|
|
238
|
+
implicitly run `sync` or `update` as part of a release build because that would make network state an
|
|
239
|
+
input. Perform updates as separate, reviewable changes and commit the pinned expanded source first.
|
|
240
|
+
|
|
241
|
+
## Handling failures
|
|
242
|
+
|
|
243
|
+
- If a command refuses replacement, inspect `git status` and the relevant differences before retrying
|
|
244
|
+
- If `.<output-name>.rollback-*` remains, compare it with the current output before deciding what to restore or remove
|
|
245
|
+
- After a partial extension update failure, inspect `git diff` before retrying
|
|
246
|
+
- Roll back a merged change by reverting the project commit so source, artifacts, and provenance return together
|
|
247
|
+
- When replacing a published SB3, follow the project's release policy and preserve history
|
|
248
|
+
|
|
249
|
+
Do not destroy Git history as a recovery shortcut. Keep the cause and affected scope inspectable.
|
package/package.json
CHANGED