@kubohiroya/sb3-toolchain 0.3.0 → 0.5.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,205 @@
1
+ # SB3展開ソース形式v1
2
+
3
+ [English](../source-format-v1.md)
4
+
5
+ ## レイアウト
6
+
7
+ ```text
8
+ SOURCE_DIR/
9
+ ├── sb3-source.json
10
+ ├── project.source.json
11
+ ├── embedded-extensions.json
12
+ ├── assets/
13
+ │ └── <assetId>.<dataFormat>
14
+ └── extensions/
15
+ └── <extensionId>.js
16
+ ```
17
+
18
+ `sb3-source.json`は、形式のバージョン、各構成要素へのパス、元のSB3におけるZIPエントリ順を記録します。
19
+
20
+ ```json
21
+ {
22
+ "formatVersion": 1,
23
+ "project": "project.source.json",
24
+ "embeddedExtensions": "embedded-extensions.json",
25
+ "assetsDirectory": "assets",
26
+ "archiveEntries": ["project.json", "<assetId>.svg"]
27
+ }
28
+ ```
29
+
30
+ ## `project.source.json`
31
+
32
+ このファイルは、元のSB3の`project.json`を2スペースインデントで整形したJSONです。配列とオブジェクトの
33
+ 順序は意味のある入力として保持されます。data URLとして埋め込まれていたTurboWarp機能拡張は、次の参照に
34
+ 置き換えられます。
35
+
36
+ ```text
37
+ embedded-extension:extensions/<extensionId>.js
38
+ ```
39
+
40
+ ビルド時には、`embedded-extensions.json`のメディアタイプ、パラメータ、エンコーディングを使用してdata URLを
41
+ 再構築します。
42
+
43
+ ## `embedded-extensions.json`
44
+
45
+ このファイルは、埋め込み機能拡張のdata URL情報と展開先パスを記録します。GitHubまたはインストール済み
46
+ npmパッケージから管理する機能拡張には、任意の`source`メタデータを追加できます。
47
+
48
+ ```json
49
+ {
50
+ "formatVersion": 1,
51
+ "extensions": [
52
+ {
53
+ "id": "example",
54
+ "path": "extensions/example.js",
55
+ "mediaType": "text/javascript",
56
+ "parameters": [],
57
+ "encoding": "base64",
58
+ "source": {
59
+ "provider": "github",
60
+ "repository": "owner/example-extension",
61
+ "ref": "main",
62
+ "resolvedCommit": "0123456789abcdef0123456789abcdef01234567",
63
+ "artifact": "dist/example.js",
64
+ "integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
65
+ "apiManifest": {
66
+ "artifact": "dist/extension-manifest.json",
67
+ "path": "extensions/example.manifest.json",
68
+ "formatVersion": 1,
69
+ "integrity": "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="
70
+ }
71
+ }
72
+ }
73
+ ]
74
+ }
75
+ ```
76
+
77
+ 完全固定したnpm依存では、GitHub固有のフィールドをパッケージ情報へ置き換えます。
78
+
79
+ ```json
80
+ {
81
+ "provider": "npm",
82
+ "package": "@owner/example-extension",
83
+ "version": "1.2.3",
84
+ "artifact": "dist/example.js",
85
+ "integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
86
+ }
87
+ ```
88
+
89
+ - `provider`: `github`または`npm`
90
+ - `repository`: `<owner>/<repository>`形式のGitHubリポジトリ
91
+ - `ref`: 更新候補として追跡するブランチ、タグ、またはコミット
92
+ - `resolvedCommit`: 現在のファイルの取得に使用した、小文字40文字のコミットSHA
93
+ - `package`: スコープを含む完全なnpmパッケージ名
94
+ - `version`: インストール済み`package.json`に記録された完全固定のsemantic version。範囲指定は不可
95
+ - `artifact`: リポジトリまたはnpmパッケージのルートを基準にしたJavaScript成果物のパス
96
+ - `integrity`: 現在のファイルのSRI形式SHA-256
97
+ - `apiManifest`: 任意で使用するAPI互換性メタデータ
98
+ - `artifact`: 同じGitHubリポジトリを基準にしたAPIマニフェストのパス
99
+ - `path`: 必須のローカルパス`extensions/<extensionId>.manifest.json`
100
+ - `formatVersion`: 対応するマニフェスト形式。現在は`1`
101
+ - `integrity`: インストール済みマニフェストのSRI形式SHA-256
102
+
103
+ 検証とビルドでは、ネットワークへ接続せずに管理対象機能拡張を検証します。
104
+
105
+ - 実ファイルのSHA-256が`integrity`と一致する
106
+ - ファイルの`// ID: <extensionId>`ヘッダーが`id`と一致する
107
+ - GitHubリポジトリ、ref、コミット、npmパッケージ、完全固定バージョン、成果物パスが安全な形式である
108
+ - `apiManifest`が存在する場合、そのJSONスキーマ、ID、形式バージョン、パス、SHA-256が有効である
109
+
110
+ 既存の展開ソースディレクトリへSB3を再importすると、同じIDとパスの`source`メタデータが保持されます。
111
+ importしたファイルが記録済みのハッシュまたはIDと一致しない場合、既存の出力を変更せずにimportを拒否します。
112
+ 新規importでは来歴を推測できないため、`source`は自動作成されません。
113
+
114
+ GitHub sourceの`extensions sync`は変更不能な`resolvedCommit`からJavaScriptと任意のAPIマニフェストを
115
+ ダウンロードします。npm sourceでは、最寄りの親`node_modules`にインストールされた完全固定パッケージから、
116
+ ネットワークを使わずに読み込みます。どちらもIDとハッシュが既存メタデータに一致する場合だけ復元します。
117
+ パッケージマネージャーで新しい完全固定npmバージョンを導入した後に`extensions update`を実行すると、成果物を
118
+ コピーして`version`とintegrityを更新します。GitHub更新では`ref`を解決して`resolvedCommit`を更新します。
119
+ どちらも候補APIマニフェストを事前に比較し、選択した全項目の検証が終わるまで展開ソースを変更しません。
120
+
121
+ 機能拡張IDの移行では、マニフェストの`id`と`path`、`project.source.json`内の既知の参照、
122
+ `extensions/<id>.js`を1回のトランザクションで変更します。`extensions update`の一部として管理対象機能拡張を
123
+ 移行する場合は、明示的に指定した`artifact`、`resolvedCommit`、`integrity`も新しい成果物に合わせて更新します。
124
+ 任意のAPIマニフェストは、明示した旧IDと新IDのトップレベルIDを正規化してから比較し、新しいIDで保存して、
125
+ 同じトランザクションで更新します。リモートファイル名も変わる場合は、`--api-manifest-artifact`で
126
+ `source.apiManifest.artifact`を明示的に更新します。
127
+
128
+ APIマニフェストファイルは展開ソースの検証入力であり、SB3アーカイブのエントリではありません。決定的なSB3の
129
+ バイト列は変わりません。マニフェストv1、互換性分類、破壊的変更の明示的な許可、ロールバックについては、
130
+ [`extension-api-compatibility.md`](extension-api-compatibility.md)を参照してください。
131
+
132
+ ### `extensionBundles`
133
+
134
+ 任意の`extensionBundles`配列を追加すると、複数の個別機能拡張を、生成SB3内だけで1つの権限単位にできます。
135
+
136
+ ```json
137
+ {
138
+ "formatVersion": 1,
139
+ "extensions": [
140
+ {
141
+ "id": "extensionone",
142
+ "path": "extensions/extensionone.js",
143
+ "mediaType": "text/javascript",
144
+ "parameters": [],
145
+ "encoding": "base64"
146
+ },
147
+ {
148
+ "id": "extensiontwo",
149
+ "path": "extensions/extensiontwo.js",
150
+ "mediaType": "text/javascript",
151
+ "parameters": [],
152
+ "encoding": "base64"
153
+ }
154
+ ],
155
+ "extensionBundles": [
156
+ {
157
+ "id": "projectbundle",
158
+ "name": "Project Extension Bundle",
159
+ "members": ["extensionone", "extensiontwo"]
160
+ }
161
+ ]
162
+ }
163
+ ```
164
+
165
+ - `id`: TurboWarpの`[a-z0-9]+`形式で、個別機能拡張と衝突しない複合機能拡張ID
166
+ - `name`: 権限確認と機能拡張カテゴリに表示される単一行の名前
167
+ - `members`: 2つ以上の個別機能拡張ID。順序によってブロックとメニューの合成順が決まる。パレットでは、
168
+ メタデータを持つ装飾済みbundle LABEL見出しとグループ間の二重separatorが追加される一方、元の機能拡張の
169
+ LABELエントリとseparatorは変更されない
170
+
171
+ 1つのメンバーを複数のbundleに所属させることはできません。個別エントリ、個別JavaScript、`source`、
172
+ `project.source.json`が引き続き信頼できる情報源です。`build`は各元opcodeに`memberId + "__"`を加え、
173
+ 出力側の`project.json`のopcode、`extensions`、`extensionURLs`、機能拡張ストレージだけをbundle IDに変更します。
174
+ 埋め込まれるbundle JavaScriptのdata URLは1つです。
175
+
176
+ bundle JavaScriptの末尾には、元の個別data URLと機能拡張の順序を格納した形式1の復元カプセルが含まれます。
177
+ 設定を削除するか、そのカプセルを含む生成SB3に対して`extensions unbundle`を実行すると、通常の出力へ
178
+ 復元できます。互換性契約と復元手順については、[`extension-bundles.md`](extension-bundles.md)を参照してください。
179
+
180
+ ## アセット
181
+
182
+ `assets/`には、`project.source.json`から参照されるコスチュームと音声が含まれます。各ファイル名は
183
+ `<assetId>.<dataFormat>`であり、`assetId`は内容のMD5と一致しなければなりません。未参照、欠落、余分な
184
+ ファイルはいずれも検証エラーです。
185
+
186
+ ## 決定的出力
187
+
188
+ - ZIPエントリは`archiveEntries`に従う
189
+ - ZIPタイムスタンプは1980-01-01 00:00:00に固定
190
+ - 圧縮レベルは6に固定
191
+ - `project.json`は末尾に改行を持つ最小JSONとして格納
192
+ - ソース形式のバージョン、入力ファイル、ツールのバージョンが同じなら、同じバイト列を生成
193
+
194
+ ## 安全性
195
+
196
+ - 絶対パス、`\`、空の構成要素、`.`、`..`を含むZIPエントリを拒否
197
+ - ソース入力としてシンボリックリンクと特殊ファイルを拒否
198
+ - ファイルシステムルート、Gitリポジトリルート、その祖先、`.git/`をimport先として拒否
199
+ - 認識できない既存ディレクトリを上書きしない
200
+ - 2段階の明示的な許可なしにGit管理対象の変更を破棄しない
201
+ - 中断された置換のロールバック領域が存在するときは、自動的に上書きしない
202
+ - 管理対象機能拡張のコミット、SHA-256、機能拡張IDをオフラインで検証
203
+ - bundle時に個別JavaScriptと来歴を保持し、互換性を確立できない契約を拒否
204
+ - GitHubからはHTTPSだけで取得し、リダイレクトを拒否してサイズを制限し、ダウンロードしたJavaScriptは
205
+ 決して実行しない
@@ -0,0 +1,265 @@
1
+ # SB3ソース管理ワークフロー
2
+
3
+ [English](../workflows.md)
4
+
5
+ この文書では、Scratch 3またはTurboWarpのSB3をGit内の展開ソースとして管理し、検証済みSB3を再ビルドする
6
+ 一般的なワークフローを説明します。各プロジェクトリポジトリでは、編集、テスト、配布の手順を個別に定義して
7
+ ください。
8
+
9
+ 展開ディレクトリのレイアウトとファイル形式については、
10
+ [`source-format-v1.md`](source-format-v1.md)を参照してください。
11
+
12
+ ## 原則
13
+
14
+ - Git内の展開ディレクトリを信頼できる情報源として扱い、生成SB3ファイルはビルド成果物として扱う
15
+ - TurboWarp Editorで編集したSB3は、差分を確認した後に限りimportする
16
+ - コミット前と配布前に`check`を実行する
17
+ - CIとリリースワークフローでは、固定したツールチェーンバージョンとコミット済み展開ソースからビルドする
18
+ - 管理対象の埋め込み機能拡張は、固定したソースコミットとSHA-256から再現する
19
+
20
+ 以下の例では、展開ソースに`app/`、エディタで保存したSB3に`tmp/edited.sb3`、生成出力に
21
+ `dist/project.sb3`を使用します。必要に応じてプロジェクト固有のパスを選択してください。
22
+
23
+ ## 初回import
24
+
25
+ TurboWarpで保存したSB3を、Gitでの管理に適したファイルへ展開します。
26
+
27
+ ```bash
28
+ sb3-toolchain import tmp/edited.sb3 --output app
29
+ sb3-toolchain check app
30
+ git status --short
31
+ ```
32
+
33
+ import後、少なくとも次の項目を確認します。
34
+
35
+ - `project.source.json`の変更がエディタで行った操作に対応している
36
+ - `assets/`へのアセット追加または削除が意図したものだけである
37
+ - `extensions/`と`embedded-extensions.json`に予期しない変更がない
38
+ - `sb3-toolchain check app`が成功する
39
+
40
+ 新規importでは、埋め込みJavaScriptの取得元は推測されません。GitHubでホストされる機能拡張を管理対象にする
41
+ 場合は、後述の来歴メタデータを追加してください。
42
+
43
+ ## 既存ソースへの再import
44
+
45
+ プロジェクトを編集した後、保存したSB3を既存の展開ソースディレクトリへimportします。
46
+
47
+ ```bash
48
+ git status --short
49
+ sb3-toolchain import tmp/edited.sb3 --output app
50
+ sb3-toolchain check app
51
+ git diff -- app
52
+ ```
53
+
54
+ 既存の展開ソースと内容が異なる場合、ツールは置換の確認を求めます。非対話環境では`--yes`によって確認を
55
+ 省略できますが、Git管理対象の未コミット変更は破棄されません。破棄される変更を確認した後に限り、両方の
56
+ オプションを指定してください。
57
+
58
+ ```bash
59
+ sb3-toolchain import tmp/edited.sb3 --output app \
60
+ --yes \
61
+ --discard-local-changes
62
+ ```
63
+
64
+ `--discard-local-changes`は復旧手段ではありません。使用する前に、必要な変更をコミットするなどして保存して
65
+ ください。`--force`オプションはありません。
66
+
67
+ 同じIDとパスを持つ管理対象機能拡張の来歴メタデータは、再import時も保持されます。SB3内のJavaScriptが
68
+ 記録済みのIDまたはSHA-256と異なる場合、実ファイルと来歴の不整合を防ぐため、既存出力を変更せずにimportを
69
+ 拒否します。
70
+
71
+ ## 検証とビルド
72
+
73
+ 展開ソースだけを検証するには`check`、SB3を生成するには`build`を使用します。
74
+
75
+ ```bash
76
+ sb3-toolchain check app
77
+ sb3-toolchain build app --output dist/project.sb3
78
+ ```
79
+
80
+ `check`と`build`はネットワークへ接続しません。ローカル入力だけを使用して、アセット参照、MD5ハッシュ、
81
+ 展開形式、埋め込み機能拡張ID、SHA-256ハッシュを検証します。
82
+
83
+ `build`はZIPエントリ順、タイムスタンプ、圧縮設定を固定します。同じツールチェーンバージョンと展開ソースから、
84
+ バイト単位で同一のSB3が生成されます。既存出力が同一なら変更しません。異なる場合は、置換の確認または
85
+ `--yes`が必要です。
86
+
87
+ 生成SB3へ書き込む前に、全ターゲットのトップレベルスクリプトを整理するには、明示的にオプションを指定します。
88
+
89
+ ```bash
90
+ sb3-toolchain build app --output dist/project.sb3 --clean-up-blocks
91
+ ```
92
+
93
+ `--clean-up-blocks`は、TurboWarpの「きれいにする」配置と同じ開始座標、列の判定範囲、余白を使用します。
94
+ ブロック、変数、リスト、コメントは削除せず、ブロックに付いたコメントはスクリプトと一緒に移動します。変換する
95
+ のは生成物内の`project.json`だけであり、展開ソースは変更しません。生成SB3をTurboWarpで開いた後は座標変更を
96
+ 元に戻せない場合があります。ソース座標へ戻すにはこのオプションを外して再ビルドしてください。
97
+
98
+ プロジェクト固有のテストに加えて、生成SB3をTurboWarpで開き、起動、主要な操作、画像、音声、埋め込み
99
+ 機能拡張の動作を確認してください。
100
+
101
+ ## 管理対象の埋め込み機能拡張
102
+
103
+ `embedded-extensions.json`の`source`オブジェクトには、GitHubコミットの来歴またはインストール済みnpm
104
+ パッケージの完全固定バージョンと、成果物パス、SHA-256を記録できます。更新時の静的互換性検査に使用する
105
+ バージョン付きAPIマニフェストも任意で設定できます。完全なスキーマは
106
+ [`source-format-v1.md`](source-format-v1.md)を参照してください。
107
+
108
+ 機能拡張コマンドの役割は次のとおりです。
109
+
110
+ | コマンド | ネットワーク | refの解決 | メタデータ更新 | 目的 |
111
+ | ----------------------- | ------------ | ---------- | -------------- | -------------------------------------- |
112
+ | `extensions status` | GitHubのみ | GitHubのみ | なし | 上流または導入済みパッケージを確認 |
113
+ | `extensions sync` | GitHubのみ | なし | なし | 宣言したsourceからファイルを復元 |
114
+ | `extensions update` | GitHubのみ | GitHubのみ | あり | 上流または導入済みパッケージを採用 |
115
+ | `extensions migrate-id` | なし | なし | ID/参照 | プロジェクトで使用中の機能拡張IDを移行 |
116
+ | `extensions bundle` | なし | なし | bundle設定 | 機能拡張を1つの権限単位へ統合 |
117
+ | `extensions unbundle` | なし | なし | 設定またはSB3 | 個別機能拡張を使用する出力へ復元 |
118
+
119
+ ### 更新の確認
120
+
121
+ ```bash
122
+ sb3-toolchain extensions status app
123
+ ```
124
+
125
+ `status`はローカルファイルを変更しません。GitHub sourceでは追跡対象refと`resolvedCommit`を比較します。
126
+ npm sourceでは、宣言した完全固定バージョンとインストール済みパッケージをネットワークなしで比較します。
127
+
128
+ ### 固定したコミットからの復元
129
+
130
+ ```bash
131
+ sb3-toolchain extensions sync app
132
+ sb3-toolchain check app
133
+ ```
134
+
135
+ `sync`は変更可能なブランチやタグを解決しません。GitHub sourceは`resolvedCommit`からダウンロードし、
136
+ npm sourceは最寄りの親`node_modules`へ導入済みの完全固定パッケージから読み込みます。JavaScriptと任意の
137
+ APIマニフェストが記録済みIDおよびSHA-256値に一致する場合に限り、ローカルファイルを置き換えます。
138
+
139
+ ### 追跡対象refの更新
140
+
141
+ ```bash
142
+ sb3-toolchain extensions update app
143
+ sb3-toolchain extensions update app EXTENSION_ID
144
+ sb3-toolchain check app
145
+ git diff -- app
146
+ ```
147
+
148
+ IDを省略すると、管理対象の全機能拡張を1回のトランザクションで更新します。ダウンロードまたは検証が1つでも
149
+ 失敗した場合、ファイルもメタデータも変更しません。
150
+
151
+ npm sourceでは、最初にプロジェクトのパッケージマネージャーで新しい完全固定バージョンを導入し、続けて
152
+ `extensions status`と`extensions update`を実行します。updateは導入済み成果物をコピーし、パッケージの
153
+ `version`とintegrityを記録します。sb3-toolchain自身はnpm registryへ問い合わせません。
154
+
155
+ `source.apiManifest`が存在する場合、同じ解決済みコミットからJavaScriptとAPIマニフェストをダウンロードします。
156
+ 互換性のある追加は報告されます。ブロックの削除、ブロック種別の変更、引数契約の変更、参照中メニューの削除、
157
+ `acceptReporters`の変更は、インストール前に拒否されます。未参照メニューの削除には互換性があります。
158
+ 報告されたすべてのパスを確認した後、意図的な破壊的更新には両方のフラグが必要です。
159
+
160
+ ```bash
161
+ sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
162
+ ```
163
+
164
+ バージョン付きマニフェスト契約、分類表、既定OFFの動作、ロールバックについては、
165
+ [`extension-api-compatibility.md`](extension-api-compatibility.md)を参照してください。
166
+
167
+ 更新PRでは、`resolvedCommit`またはnpmの`version`、JavaScriptとマニフェストのintegrity、互換性パス、
168
+ 両成果物をまとめて確認し、生成SB3で機能拡張の主要機能をテストします。
169
+
170
+ ## 機能拡張IDの移行
171
+
172
+ 機能拡張IDはopcodeとmonitorに保存されるため、ファイル名やマニフェストだけを手作業で変更しないでください。
173
+ dry runから始め、分類済み参照と未分類参照の両方を確認します。
174
+
175
+ ```bash
176
+ sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID
177
+ ```
178
+
179
+ 新しいIDを宣言するJavaScriptを用意して結果を確認し、適用します。
180
+
181
+ ```bash
182
+ sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID --yes
183
+ sb3-toolchain check app
184
+ git diff -- app
185
+ ```
186
+
187
+ GitHub管理対象機能拡張では、上流成果物の更新とID移行を1回のトランザクションにできます。
188
+
189
+ ```bash
190
+ sb3-toolchain extensions update app OLD_ID \
191
+ --migrate-id NEW_ID \
192
+ --artifact dist/NEW_ID.js
193
+ ```
194
+
195
+ 上流の成果物パスも変わった場合に限り`--artifact`を指定します。影響するスキーマ、衝突検査、未分類参照、
196
+ ロールバックについては、[`extension-id-migration.md`](extension-id-migration.md)を参照してください。
197
+
198
+ ## unsandboxed権限を1回の確認に統合
199
+
200
+ 複数の埋め込み機能拡張を含むプロジェクトでは、静的bundleを任意で使用できます。元のJavaScript、ID、opcode、
201
+ 来歴は変更されず、ビルド出力だけが1つの複合機能拡張へ変換されます。
202
+
203
+ ```bash
204
+ sb3-toolchain extensions bundle app \
205
+ --id projectbundle \
206
+ --name "Project Extension Bundle" \
207
+ extensionone extensiontwo
208
+ sb3-toolchain extensions bundle app \
209
+ --id projectbundle \
210
+ --name "Project Extension Bundle" \
211
+ extensionone extensiontwo \
212
+ --yes
213
+ sb3-toolchain check app
214
+ sb3-toolchain build app --output dist/project.sb3 --yes
215
+ ```
216
+
217
+ プロジェクトレベルの自動テストと実際のTurboWarpでのスモークテストを使用し、bundle前後での同等な動作、
218
+ 1回だけの権限確認、保存後の再読み込み成功を検証します。問題がある場合は、保持されている個別機能拡張へ
219
+ 復元します。
220
+
221
+ ```bash
222
+ sb3-toolchain extensions unbundle app projectbundle
223
+ sb3-toolchain extensions unbundle app projectbundle --yes
224
+ sb3-toolchain check app
225
+ sb3-toolchain build app --output dist/project.sb3 --yes
226
+ ```
227
+
228
+ 展開ソースが利用できない場合でも、このバージョンのツールチェーンで生成したSB3は直接unbundleできます。
229
+ 最初のコマンドはdry runで、`--yes`を指定した場合に限り出力を書き込みます。
230
+
231
+ ```bash
232
+ sb3-toolchain extensions unbundle \
233
+ dist/project.sb3 projectbundle \
234
+ --output dist/project.unbundled.sb3
235
+ sb3-toolchain extensions unbundle \
236
+ dist/project.sb3 projectbundle \
237
+ --output dist/project.unbundled.sb3 \
238
+ --yes
239
+ ```
240
+
241
+ 互換性契約、ソースコメント、opcodeとストレージの変換、直接unbundleの制限、再import時の注意事項については、
242
+ [`extension-bundles.md`](extension-bundles.md)を参照してください。
243
+
244
+ ## CIと配布
245
+
246
+ 依存関係のバージョンを固定し、CIで少なくとも次のコマンドを実行します。
247
+
248
+ ```bash
249
+ sb3-toolchain check app
250
+ sb3-toolchain build app --output dist/project.sb3 --yes
251
+ ```
252
+
253
+ プロジェクトレベルの自動テストと手動検証に合格したSB3だけを配布してください。ネットワーク状態が入力になって
254
+ しまうため、リリースビルドの一部として`sync`や`update`を暗黙的に実行しないでください。更新は独立した
255
+ レビュー可能な変更として行い、固定した展開ソースを先にコミットします。
256
+
257
+ ## 失敗時の対応
258
+
259
+ - コマンドが置換を拒否した場合は、再試行する前に`git status`と該当する差分を確認する
260
+ - `.<output-name>.rollback-*`が残っている場合は、復元または削除を決める前に現在の出力と比較する
261
+ - 機能拡張更新が途中で失敗した場合は、再試行する前に`git diff`を確認する
262
+ - merge済み変更はプロジェクトコミットをrevertし、ソース、成果物、来歴をまとめて元に戻す
263
+ - 公開済みSB3を置き換える場合は、プロジェクトのリリースポリシーに従い、履歴を保持する
264
+
265
+ 復旧の近道としてGit履歴を破壊しないでください。原因と影響範囲を調査可能な状態に保ちます。
@@ -1,5 +1,7 @@
1
1
  # SB3 expanded source format v1
2
2
 
3
+ [日本語版](ja/source-format-v1.md)
4
+
3
5
  ## Layout
4
6
 
5
7
  ```text
@@ -42,7 +44,7 @@ reconstruct the data URL.
42
44
  ## `embedded-extensions.json`
43
45
 
44
46
  This file records embedded extension data URL information and extraction paths. Optional `source`
45
- metadata can be added for an extension managed from GitHub.
47
+ metadata can be added for an extension managed from GitHub or an installed npm package.
46
48
 
47
49
  ```json
48
50
  {
@@ -73,10 +75,25 @@ metadata can be added for an extension managed from GitHub.
73
75
  }
74
76
  ```
75
77
 
78
+ For an exact npm dependency, replace the GitHub-specific fields with the package identity:
79
+
80
+ ```json
81
+ {
82
+ "provider": "npm",
83
+ "package": "@owner/example-extension",
84
+ "version": "1.2.3",
85
+ "artifact": "dist/example.js",
86
+ "integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
87
+ }
88
+ ```
89
+
90
+ - `provider`: `github` or `npm`
76
91
  - `repository`: GitHub repository in `<owner>/<repository>` form
77
92
  - `ref`: branch, tag, or commit to track for update candidates
78
93
  - `resolvedCommit`: lowercase 40-character commit SHA used to obtain the current file
79
- - `artifact`: JavaScript artifact path relative to the repository root
94
+ - `package`: exact npm package name, including its scope when applicable
95
+ - `version`: exact semantic version recorded in the installed package's `package.json`; ranges are not accepted
96
+ - `artifact`: JavaScript artifact path relative to the repository or npm package root
80
97
  - `integrity`: SRI-form SHA-256 of the current file
81
98
  - `apiManifest`: optional, opt-in API compatibility metadata
82
99
  - `artifact`: API manifest path relative to the same GitHub repository
@@ -88,7 +105,7 @@ Validation and builds verify managed extensions without accessing the network:
88
105
 
89
106
  - The actual file SHA-256 matches `integrity`
90
107
  - The file's `// ID: <extensionId>` header matches `id`
91
- - The repository, ref, commit, and artifact path use safe forms
108
+ - The GitHub repository, ref, commit, npm package, exact version, and artifact path use safe forms
92
109
  - When `apiManifest` exists, its JSON schema, ID, format version, path, and SHA-256 are valid
93
110
 
94
111
  Re-importing an SB3 into an existing expanded source directory preserves `source` metadata for the
@@ -96,12 +113,14 @@ same ID and path. If the imported file does not match the recorded hash or ID, t
96
113
  without changing the existing output. A new import cannot infer provenance, so it does not create
97
114
  `source` automatically.
98
115
 
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.
116
+ For GitHub sources, `extensions sync` downloads the JavaScript and optional API manifest using the
117
+ immutable `resolvedCommit`. For npm sources, it reads them from the exact package installed in the
118
+ nearest ancestor `node_modules` directory without network access. Both paths restore local files only
119
+ when IDs and hashes match existing metadata. After the package manager installs a newer exact npm
120
+ version, `extensions update` copies its artifacts and updates `version` and integrity metadata.
121
+ GitHub updates instead resolve `ref` and update `resolvedCommit`. Candidate API manifests are compared
122
+ before either type is installed. The expanded source remains unchanged until every selected entry has
123
+ been validated.
105
124
 
106
125
  An extension ID migration changes the manifest `id` and `path`, known references in
107
126
  `project.source.json`, and `extensions/<id>.js` in one transaction. When a managed extension is
package/docs/workflows.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # SB3 source-management workflows
2
2
 
3
+ [日本語版](ja/workflows.md)
4
+
3
5
  This document describes the common workflow for managing a Scratch 3 or TurboWarp SB3 as expanded
4
6
  source in Git and rebuilding a validated SB3. Each project repository should define its own editing,
5
7
  testing, and distribution procedures.
@@ -81,22 +83,35 @@ expanded format, embedded extension IDs, and SHA-256 hashes using only local inp
81
83
  and expanded source produce a bit-for-bit identical SB3. An identical existing output is left
82
84
  untouched. A differing output requires replacement confirmation or `--yes`.
83
85
 
86
+ To arrange the top-level scripts in every target before writing the generated SB3, opt in explicitly:
87
+
88
+ ```bash
89
+ sb3-toolchain build app --output dist/project.sb3 --clean-up-blocks
90
+ ```
91
+
92
+ `--clean-up-blocks` uses TurboWarp's cleaned-layout starting coordinates, column grouping tolerance,
93
+ and spacing. It preserves blocks, variables, lists, and comments; attached comments move with their
94
+ scripts. Only the generated `project.json` is transformed, so the expanded source remains unchanged.
95
+ TurboWarp might not be able to undo these coordinate changes after opening the generated SB3. Omit
96
+ the option and rebuild to roll back to the source coordinates.
97
+
84
98
  In addition to project-specific tests, open the generated SB3 in TurboWarp and verify startup, primary
85
99
  operations, images, sounds, and embedded extension behavior.
86
100
 
87
101
  ## Managed embedded extensions
88
102
 
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.
103
+ The `source` object in `embedded-extensions.json` can record either GitHub commit provenance or an
104
+ exact installed npm package version, together with its artifact path and SHA-256. It can also opt in
105
+ to a versioned API manifest for static update compatibility checks. See
106
+ [`source-format-v1.md`](source-format-v1.md) for the complete schema.
92
107
 
93
108
  The extension commands have the following roles:
94
109
 
95
110
  | Command | Network | Resolve ref | Metadata update | Purpose |
96
111
  | ----------------------- | ------- | ----------- | --------------- | ------------------------------------------- |
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 |
112
+ | `extensions status` | GitHub | GitHub | No | Check the upstream or installed package |
113
+ | `extensions sync` | GitHub | No | No | Restore files from the declared source |
114
+ | `extensions update` | GitHub | GitHub | Yes | Adopt the upstream or installed package |
100
115
  | `extensions migrate-id` | No | No | IDs/references | Migrate an extension ID used by the project |
101
116
  | `extensions bundle` | No | No | Bundle config | Combine extensions into one permission unit |
102
117
  | `extensions unbundle` | No | No | Config or SB3 | Restore output with individual extensions |
@@ -107,8 +122,8 @@ The extension commands have the following roles:
107
122
  sb3-toolchain extensions status app
108
123
  ```
109
124
 
110
- `status` does not change local files. Review upstream changes for extensions whose tracked ref differs
111
- from `resolvedCommit`, then decide whether to update.
125
+ `status` does not change local files. GitHub sources compare the tracked ref with `resolvedCommit`.
126
+ npm sources compare the declared exact version with the installed package without network access.
112
127
 
113
128
  ### Restore from a pinned commit
114
129
 
@@ -117,9 +132,9 @@ sb3-toolchain extensions sync app
117
132
  sb3-toolchain check app
118
133
  ```
119
134
 
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.
135
+ `sync` does not resolve a mutable branch or tag. GitHub sources download from `resolvedCommit`; npm
136
+ sources read from the exact package installed in the nearest ancestor `node_modules`. It replaces
137
+ local files only when JavaScript and an optional API manifest match recorded IDs and SHA-256 values.
123
138
 
124
139
  ### Update a tracked ref
125
140
 
@@ -133,6 +148,10 @@ git diff -- app
133
148
  Omitting the ID updates all managed extensions as one transaction. If any download or validation
134
149
  fails, neither files nor metadata are changed.
135
150
 
151
+ For an npm source, first use the project package manager to install a new exact dependency version,
152
+ then run `extensions status` and `extensions update`. The update copies the installed artifacts and
153
+ records their package `version` and integrity. It never queries the npm registry itself.
154
+
136
155
  When `source.apiManifest` is present, the update downloads JavaScript and the API manifest from the
137
156
  same resolved commit. Compatible additions are reported. A removed block, changed block type,
138
157
  argument-contract change, removed referenced menu, or `acceptReporters` change is rejected before
@@ -146,8 +165,9 @@ sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
146
165
  See [`extension-api-compatibility.md`](extension-api-compatibility.md) for the versioned manifest
147
166
  contract, classification table, default-off behavior, and rollback.
148
167
 
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.
168
+ In an update PR, review `resolvedCommit` or npm `version`, JavaScript and manifest integrity,
169
+ compatibility paths, and both artifacts together, then test the extension's primary features in the
170
+ generated SB3.
151
171
 
152
172
  ## Migrate an extension ID
153
173