@kubohiroya/sb3-toolchain 0.1.1 → 0.2.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.
@@ -1,46 +1,47 @@
1
- # 埋め込み拡張IDの移行
1
+ # Migrating embedded extension IDs
2
2
 
3
- TurboWarpで読み込み済みの拡張IDは、project内のopcodeやmonitorにも保存されます。
4
- `extensions migrate-id`はJSON全体の文字列置換を行わず、SB3 source format v1で意味が
5
- 確定している参照だけを変更します。
3
+ TurboWarp stores the IDs of loaded extensions in project opcodes and monitors. `extensions migrate-id`
4
+ does not perform a global string replacement. It changes only references whose meaning is defined by
5
+ SB3 source format v1.
6
6
 
7
- ## dry-runと適用
7
+ ## Dry run and apply
8
8
 
9
- 単独の移行コマンドは既定でdry-runです。
9
+ The standalone migration command is a dry run by default.
10
10
 
11
11
  ```bash
12
12
  sb3-toolchain extensions migrate-id app --from twOld --to newext
13
13
  ```
14
14
 
15
- 出力される分類済み変更件数と`Unclassified`参照を確認し、新IDを宣言するJavaScript成果物を
16
- `extensions/twOld.js`へ用意してから明示的に適用します。
15
+ Review the classified change counts and `Unclassified` references. Before applying the migration,
16
+ place a JavaScript artifact that declares the new ID at `extensions/twOld.js`.
17
17
 
18
18
  ```bash
19
19
  sb3-toolchain extensions migrate-id app --from twOld --to newext --yes
20
20
  ```
21
21
 
22
- 新IDはTurboWarp公式形式の`[a-z0-9]+`でなければなりません。既存のmanifest、
23
- `extensionURLs`、または`project.extensions`に新IDが存在する場合はcollisionとして
24
- 拒否します。
22
+ The new ID must use TurboWarp's official `[a-z0-9]+` format. The migration is rejected as a collision
23
+ if the new ID already exists in the manifest, `extensionURLs`, or `project.extensions`.
25
24
 
26
- ## 分類して変更する参照
25
+ ## Classified references
27
26
 
28
- - `project.source.json`の`extensions[]`にある完全一致ID
29
- - `extensionURLs`の完全一致keyと埋め込み拡張value
30
- - `targets[*].blocks[*].opcode`の`<oldId>_`完全prefix
31
- - menu blockのopcode(通常のblockと同じschema)
32
- - `monitors[*].opcode`の`<oldId>_`完全prefix
33
- - `embedded-extensions.json`の`id`と`path`
34
- - `extensions/<oldId>.js`から`extensions/<newId>.js`へのファイル名変更
27
+ The tool changes the following references:
35
28
 
36
- 変数名、list名、blockのliteral、metadata、別拡張のopcodeなどに旧IDを含む文字列は
37
- 変更しません。これらはJSON Pointer付きの未分類参照としてdry-run結果へ出すため、人が
38
- 意味を確認できます。
29
+ - Exact IDs in `project.source.json` `extensions[]`
30
+ - Exact `extensionURLs` keys and embedded-extension values
31
+ - Exact `<oldId>_` prefixes in `targets[*].blocks[*].opcode`
32
+ - Menu block opcodes, which use the ordinary block schema
33
+ - Exact `<oldId>_` prefixes in `monitors[*].opcode`
34
+ - `id` and `path` in `embedded-extensions.json`
35
+ - The filename from `extensions/<oldId>.js` to `extensions/<newId>.js`
39
36
 
40
- ## GitHub管理対象
37
+ Strings containing the old ID in variable names, list names, block literals, metadata, or another
38
+ extension's opcode are not changed. They appear in the dry-run output as unclassified references
39
+ with JSON Pointers so that a person can determine their meaning.
41
40
 
42
- 管理対象拡張では、上流リポジトリが新IDを宣言する成果物を公開したあと、更新と移行を
43
- 一体で実行する方法を推奨します。
41
+ ## GitHub-managed extensions
42
+
43
+ For a managed extension, the recommended workflow combines the update and migration after the
44
+ upstream repository publishes an artifact declaring the new ID.
44
45
 
45
46
  ```bash
46
47
  sb3-toolchain extensions update app twOld \
@@ -48,12 +49,13 @@ sb3-toolchain extensions update app twOld \
48
49
  --artifact dist/newext.js
49
50
  ```
50
51
 
51
- `--artifact`は上流の成果物パスも変わる場合だけ指定します。ツールは追跡refを固定commitへ
52
- 解決し、そのcommitから新成果物を取得します。`// ID: newext`を宣言しない成果物、
53
- collision、不正な新IDは、ローカルファイルを変更する前に拒否します。
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.
54
55
 
55
- ## 検証とロールバック
56
+ ## Validation and rollback
56
57
 
57
- 適用候補について通常のsource検証と決定的SB3 buildを完了してから、展開ディレクトリを
58
- transactionalに置換します。途中失敗時は元ディレクトリを自動復旧します。マージ後に
59
- 戻す場合は、作品側の移行commitをrevertし、旧ID・旧成果物・旧provenanceを同時に戻します。
58
+ The tool completes normal source validation and a deterministic candidate SB3 build before replacing
59
+ the expanded source directory transactionally. It restores the original directory automatically if
60
+ replacement fails. To roll back after merge, revert the project migration commit so that the old ID,
61
+ artifact, and provenance return together.
@@ -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
  {
@@ -66,54 +67,104 @@ embedded-extension:extensions/<extensionId>.js
66
67
  }
67
68
  ```
68
69
 
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を実行しない
70
+ - `repository`: GitHub repository in `<owner>/<repository>` form
71
+ - `ref`: branch, tag, or commit to track for update candidates
72
+ - `resolvedCommit`: lowercase 40-character commit SHA used to obtain the current file
73
+ - `artifact`: JavaScript artifact path relative to the repository root
74
+ - `integrity`: SRI-form SHA-256 of the current file
75
+
76
+ Validation and builds verify managed extensions without accessing the network:
77
+
78
+ - The actual file SHA-256 matches `integrity`
79
+ - The file's `// ID: <extensionId>` header matches `id`
80
+ - The repository, ref, commit, and artifact path use safe forms
81
+
82
+ Re-importing an SB3 into an existing expanded source directory preserves `source` metadata for the
83
+ same ID and path. If the imported file does not match the recorded hash or ID, the import is rejected
84
+ without changing the existing output. A new import cannot infer provenance, so it does not create
85
+ `source` automatically.
86
+
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.
92
+
93
+ An extension ID migration changes the manifest `id` and `path`, known references in
94
+ `project.source.json`, and `extensions/<id>.js` in one transaction. When a managed extension is
95
+ migrated as part of `extensions update`, `artifact` when explicitly supplied, `resolvedCommit`, and
96
+ `integrity` are also updated for the new artifact.
97
+
98
+ ### `extensionBundles`
99
+
100
+ Add the optional `extensionBundles` array to make multiple individual extensions one permission unit
101
+ only in the generated SB3.
102
+
103
+ ```json
104
+ {
105
+ "formatVersion": 1,
106
+ "extensions": [
107
+ {
108
+ "id": "extensionone",
109
+ "path": "extensions/extensionone.js",
110
+ "mediaType": "text/javascript",
111
+ "parameters": [],
112
+ "encoding": "base64"
113
+ },
114
+ {
115
+ "id": "extensiontwo",
116
+ "path": "extensions/extensiontwo.js",
117
+ "mediaType": "text/javascript",
118
+ "parameters": [],
119
+ "encoding": "base64"
120
+ }
121
+ ],
122
+ "extensionBundles": [
123
+ {
124
+ "id": "projectbundle",
125
+ "name": "Project Extension Bundle",
126
+ "members": ["extensionone", "extensiontwo"]
127
+ }
128
+ ]
129
+ }
130
+ ```
131
+
132
+ - `id`: composite extension ID in TurboWarp's `[a-z0-9]+` form that does not collide with an individual extension
133
+ - `name`: single-line name displayed in the permission prompt and extension category
134
+ - `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
135
+
136
+ A member cannot belong to more than one bundle. Individual entries, individual JavaScript, `source`,
137
+ and `project.source.json` remain authoritative. `build` adds `memberId + "__"` to each original opcode
138
+ and changes only the output `project.json` opcodes, `extensions`, `extensionURLs`, and extension storage
139
+ to the bundle ID. It embeds one bundle JavaScript data URL.
140
+
141
+ The end of the bundle JavaScript contains a format 1 recovery capsule with the original individual
142
+ data URLs and extension order. Removing the configuration or running `extensions unbundle` against a
143
+ generated SB3 containing that capsule restores the ordinary output. See
144
+ [`extension-bundles.md`](extension-bundles.md) for the compatibility contract and restoration steps.
145
+
146
+ ## Assets
147
+
148
+ `assets/` contains costumes and sounds referenced by `project.source.json`. Each filename is
149
+ `<assetId>.<dataFormat>`, and `assetId` must match the MD5 of its contents. An unreferenced, missing,
150
+ or extra file is a validation error.
151
+
152
+ ## Deterministic output
153
+
154
+ - ZIP entries follow `archiveEntries`
155
+ - ZIP timestamps are fixed at 1980-01-01 00:00:00
156
+ - Compression level is fixed at 6
157
+ - `project.json` is stored as minimal JSON with a trailing newline
158
+ - The same source format version, input files, and tool version produce the same byte sequence
159
+
160
+ ## Safety
161
+
162
+ - Reject ZIP entries containing absolute paths, `\`, empty components, `.`, or `..`
163
+ - Reject symbolic links and special files as source input
164
+ - Reject a filesystem root, Git repository root, its ancestor, or `.git/` as an import destination
165
+ - Never overwrite an unrecognized existing directory
166
+ - Never discard Git-managed changes without the explicit two-stage override
167
+ - Never overwrite automatically when an interrupted replacement rollback area is present
168
+ - Verify managed extensions offline against their commit, SHA-256, and extension ID
169
+ - Preserve individual JavaScript and provenance during bundling and reject contracts whose compatibility cannot be established
170
+ - Fetch from GitHub only over HTTPS with redirects rejected and a size limit, and never execute downloaded JavaScript
@@ -0,0 +1,235 @@
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. See [`source-format-v1.md`](source-format-v1.md) for the
91
+ 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 a local file only when the artifact ID and SHA-256 match the recorded metadata.
122
+
123
+ ### Update a tracked ref
124
+
125
+ ```bash
126
+ sb3-toolchain extensions update app
127
+ sb3-toolchain extensions update app EXTENSION_ID
128
+ sb3-toolchain check app
129
+ git diff -- app
130
+ ```
131
+
132
+ Omitting the ID updates all managed extensions as one transaction. If any download or validation
133
+ fails, neither files nor metadata are changed.
134
+
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.
137
+
138
+ ## Migrate an extension ID
139
+
140
+ An extension ID is stored in opcodes and monitors, so do not change only its filename or manifest by
141
+ hand. Start with a dry run and inspect both classified and unclassified references.
142
+
143
+ ```bash
144
+ sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID
145
+ ```
146
+
147
+ Prepare JavaScript declaring the new ID, review the result, and then apply it.
148
+
149
+ ```bash
150
+ sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID --yes
151
+ sb3-toolchain check app
152
+ git diff -- app
153
+ ```
154
+
155
+ For a GitHub-managed extension, the upstream artifact update and ID migration can be one transaction.
156
+
157
+ ```bash
158
+ sb3-toolchain extensions update app OLD_ID \
159
+ --migrate-id NEW_ID \
160
+ --artifact dist/NEW_ID.js
161
+ ```
162
+
163
+ Specify `--artifact` only when the upstream artifact path also changed. See
164
+ [`extension-id-migration.md`](extension-id-migration.md) for the affected schema, collision checks,
165
+ unclassified references, and rollback details.
166
+
167
+ ## Combine unsandboxed permission into one prompt
168
+
169
+ A project containing several embedded extensions can opt in to a static bundle. Original JavaScript,
170
+ IDs, opcodes, and provenance remain unchanged; only build output is transformed into one composite
171
+ extension.
172
+
173
+ ```bash
174
+ sb3-toolchain extensions bundle app \
175
+ --id projectbundle \
176
+ --name "Project Extension Bundle" \
177
+ extensionone extensiontwo
178
+ sb3-toolchain extensions bundle app \
179
+ --id projectbundle \
180
+ --name "Project Extension Bundle" \
181
+ extensionone extensiontwo \
182
+ --yes
183
+ sb3-toolchain check app
184
+ sb3-toolchain build app --output dist/project.sb3 --yes
185
+ ```
186
+
187
+ Use project-level automated tests and a real TurboWarp smoke test to verify equivalent behavior before
188
+ and after bundling, a single permission prompt, and successful reload after saving. If there is a
189
+ problem, restore the preserved individual extensions.
190
+
191
+ ```bash
192
+ sb3-toolchain extensions unbundle app projectbundle
193
+ sb3-toolchain extensions unbundle app projectbundle --yes
194
+ sb3-toolchain check app
195
+ sb3-toolchain build app --output dist/project.sb3 --yes
196
+ ```
197
+
198
+ An SB3 generated by this version of the toolchain can also be unbundled directly when the expanded
199
+ source is unavailable. The first command is a dry run; output is written only with `--yes`.
200
+
201
+ ```bash
202
+ sb3-toolchain extensions unbundle \
203
+ dist/project.sb3 projectbundle \
204
+ --output dist/project.unbundled.sb3
205
+ sb3-toolchain extensions unbundle \
206
+ dist/project.sb3 projectbundle \
207
+ --output dist/project.unbundled.sb3 \
208
+ --yes
209
+ ```
210
+
211
+ See [`extension-bundles.md`](extension-bundles.md) for the compatibility contract, source comments,
212
+ opcode and storage transformations, direct-unbundle limitations, and re-import precautions.
213
+
214
+ ## CI and distribution
215
+
216
+ Pin dependency versions and run at least the following in CI:
217
+
218
+ ```bash
219
+ sb3-toolchain check app
220
+ sb3-toolchain build app --output dist/project.sb3 --yes
221
+ ```
222
+
223
+ Distribute only an SB3 that passed project-level automated tests and manual verification. Do not
224
+ implicitly run `sync` or `update` as part of a release build because that would make network state an
225
+ input. Perform updates as separate, reviewable changes and commit the pinned expanded source first.
226
+
227
+ ## Handling failures
228
+
229
+ - If a command refuses replacement, inspect `git status` and the relevant differences before retrying
230
+ - If `.<output-name>.rollback-*` remains, compare it with the current output before deciding what to restore or remove
231
+ - After a partial extension update failure, inspect `git diff` before retrying
232
+ - Roll back a merged change by reverting the project commit so source, artifacts, and provenance return together
233
+ - When replacing a published SB3, follow the project's release policy and preserve history
234
+
235
+ 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.2.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/build.js CHANGED
@@ -103,8 +103,13 @@ async function installArchiveTransactionally(archive, outputPath, expectedOutput
103
103
  }
104
104
  }
105
105
 
106
- export async function buildSb3({confirmReplace, outputPath, sourceDirectory, yes = false}) {
107
- assert(typeof sourceDirectory === 'string', 'SB3 source directory is required.');
106
+ export async function writeSb3Archive({
107
+ archive,
108
+ confirmReplace = undefined,
109
+ outputPath,
110
+ yes = false,
111
+ }) {
112
+ assert(archive instanceof Uint8Array, 'SB3 archive contents are required.');
108
113
  assert(typeof outputPath === 'string', 'SB3 output path is required.');
109
114
  const resolvedOutputPath = path.resolve(outputPath);
110
115
  assert(
@@ -112,12 +117,10 @@ export async function buildSb3({confirmReplace, outputPath, sourceDirectory, yes
112
117
  `SB3 output path must use the .sb3 extension: ${resolvedOutputPath}`,
113
118
  );
114
119
  await assertNoInterruptedRollback(resolvedOutputPath);
115
- const built = await createDeterministicSb3(sourceDirectory);
116
120
  const existingOutput = await inspectOutput(resolvedOutputPath);
117
121
  if (existingOutput.exists) {
118
- if (Buffer.compare(existingOutput.contents, Buffer.from(built.archive)) === 0) {
122
+ if (Buffer.compare(existingOutput.contents, Buffer.from(archive)) === 0) {
119
123
  return {
120
- ...built,
121
124
  changed: false,
122
125
  outputPath: resolvedOutputPath,
123
126
  rollbackCleanupWarning: null,
@@ -138,14 +141,25 @@ export async function buildSb3({confirmReplace, outputPath, sourceDirectory, yes
138
141
 
139
142
  await mkdir(path.dirname(resolvedOutputPath), {recursive: true});
140
143
  const rollbackCleanupWarning = await installArchiveTransactionally(
141
- built.archive,
144
+ archive,
142
145
  resolvedOutputPath,
143
146
  existingOutput,
144
147
  );
145
148
  return {
146
- ...built,
147
149
  changed: true,
148
150
  outputPath: resolvedOutputPath,
149
151
  rollbackCleanupWarning,
150
152
  };
151
153
  }
154
+
155
+ export async function buildSb3({confirmReplace, outputPath, sourceDirectory, yes = false}) {
156
+ assert(typeof sourceDirectory === 'string', 'SB3 source directory is required.');
157
+ const built = await createDeterministicSb3(sourceDirectory);
158
+ const written = await writeSb3Archive({
159
+ archive: built.archive,
160
+ confirmReplace,
161
+ outputPath,
162
+ yes,
163
+ });
164
+ return {...built, ...written};
165
+ }