@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.
@@ -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のワークフローに戻ります。
@@ -1,6 +1,6 @@
1
- # SB3展開ソース形式 v1
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`は形式バージョン、各構成要素のパス、元SB3のZIPエントリ順を保持します。
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
- 元SB3の`project.json`を2スペースで整形したJSONです。配列とオブジェクトの順序は
31
- 意味のある入力として保持します。data URLで埋め込まれていたTurboWarp拡張は次の参照へ
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
- ビルド時には`embedded-extensions.json`のメディアタイプ、パラメーター、エンコーディングを
39
- 使ってdata URLへ戻します。
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
- 埋め込み拡張のdata URL情報と展開先を保持します。GitHub上で管理する拡張には、任意の
44
- `source`メタデータを追加できます。
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>`形式のGitHubリポジトリ
70
- - `ref`: 更新候補を追跡するbranch、tag、またはcommit
71
- - `resolvedCommit`: 現在の実ファイルを取得した小文字40桁のcommit SHA
72
- - `artifact`: リポジトリルートから見たJavaScript成果物の相対パス
73
- - `integrity`: 現在の実ファイルに対するSRI形式のSHA-256
74
-
75
- `source`を持つ拡張について、検証とビルドはネットワークへ接続せず、次を確認します。
76
-
77
- - 実ファイルのSHA-256が`integrity`と一致する
78
- - 実ファイルの`// ID: <extensionId>`ヘッダーが`id`と一致する
79
- - リポジトリ、ref、commit、成果物パスが安全な形式である
80
-
81
- 既存の展開ディレクトリへSB3を再importすると、同じIDとパスに対応する`source`を維持します。
82
- 再importされた実ファイルが記録済みハッシュまたはIDと一致しない場合は、既存出力を変更
83
- しません。新規importは由来を推測できないため、`source`を自動生成しません。
84
-
85
- `extensions sync`は`resolvedCommit`を固定入力として`artifact`を取得し、既存の
86
- `integrity`とIDに一致する場合だけローカルファイルを復元します。`extensions update`は
87
- `ref`をGitHub APIで解決し、そのcommitから取得した成果物に合わせて`resolvedCommit`と
88
- `integrity`を更新します。複数entryの取得と検証がすべて成功するまで、展開ソースは変更
89
- されません。
90
-
91
- 拡張IDの変更では、manifestの`id`と`path`、`project.source.json`の既知参照、
92
- `extensions/<id>.js`を同じtransactionで移行します。管理対象拡張を`extensions update`
93
- と同時に移行した場合は、`artifact`(明示時)、`resolvedCommit`、`integrity`も新成果物に
94
- 合わせて更新します。
95
-
96
- ## アセット
97
-
98
- `assets/`には`project.source.json`から参照されるコスチュームと音声を置きます。
99
- 各ファイル名は`<assetId>.<dataFormat>`であり、`assetId`は内容のMD5と一致しなければ
100
- なりません。未参照、欠損、余分なファイルは検証エラーです。
101
-
102
- ## 決定的出力
103
-
104
- - ZIPエントリ順は`archiveEntries`に従う
105
- - ZIPタイムスタンプは1980-01-01 00:00:00に固定
106
- - 圧縮レベルは6に固定
107
- - `project.json`は末尾改行付きの最小JSONとして格納
108
- - 同じソース形式バージョン、入力ファイル、ツールバージョンから同じバイト列を生成
109
-
110
- ## 安全性
111
-
112
- - 絶対パス、`\`、空要素、`.`、`..`を含むZIPエントリを拒否
113
- - シンボリックリンクまたは特殊ファイルをソースとして受理しない
114
- - import先のファイルシステムルート、Gitリポジトリルート、その祖先、`.git/`を拒否
115
- - 認識できない既存ディレクトリを上書きしない
116
- - Git管理中の差分は明示的な二段階指定なしに破棄しない
117
- - 置換中断時のロールバック領域を検出した場合は自動上書きしない
118
- - 管理対象の拡張は、ネットワークに依存せずcommit、SHA-256、拡張IDの整合性を検証
119
- - GitHub取得はHTTPS・redirect拒否・サイズ上限付きとし、取得したJavaScriptを実行しない
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/sb3-toolchain",
3
- "version": "0.1.1",
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",