@kubohiroya/sb3-toolchain 0.3.0 → 0.4.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.ja.md ADDED
@@ -0,0 +1,147 @@
1
+ # sb3-toolchain
2
+
3
+ [English](README.md)
4
+
5
+ Scratch 3およびTurboWarpの`.sb3`プロジェクトを、Gitで差分を確認できる展開ソースとして管理し、
6
+ 同じ入力からバイト単位で同一のSB3ファイルを再ビルドするためのNode.jsツールチェーンです。
7
+
8
+ ## 特長
9
+
10
+ - SB3を、整形済みの`project.source.json`、アセット、埋め込み機能拡張へ安全に展開
11
+ - アセット参照、MD5ハッシュ、ZIPエントリ、埋め込み機能拡張の対応関係を検証
12
+ - GitHubでホストされる埋め込み機能拡張のコミットとSHA-256ハッシュを記録し、オフラインで検証
13
+ - 埋め込みJavaScriptを置き換える前に、バージョン付き機能拡張APIマニフェストを任意で比較
14
+ - 元のJavaScriptを削除せず、複数の機能拡張を1つの権限単位へ静的にbundleし、展開ソースまたは
15
+ bundle済みSB3から復元
16
+ - ZIPエントリ順、タイムスタンプ、圧縮設定を固定した決定的ビルド
17
+ - import時に未コミットのGit変更を保護
18
+ - トランザクションによる置換とロールバックで既存出力を保護
19
+ - CLIとJavaScript APIの両方を提供
20
+
21
+ ## 必要環境
22
+
23
+ - Node.js 22.12.0以降
24
+ - pnpm 11
25
+
26
+ ## インストール
27
+
28
+ 再現可能なインストールのため、検証済みのnpmバージョンを固定します。
29
+
30
+ ```bash
31
+ pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.4.0
32
+ ```
33
+
34
+ ## クイックスタート
35
+
36
+ TurboWarpで保存したSB3を展開して検証し、再ビルドします。
37
+
38
+ ```bash
39
+ sb3-toolchain import tmp/project.sb3 --output app
40
+ sb3-toolchain check app
41
+ sb3-toolchain build app --output dist/project.sb3
42
+ ```
43
+
44
+ プロジェクトリポジトリに推奨する信頼できる唯一の情報源、再import、置換保護、機能拡張更新、CIの
45
+ ワークフローについては、[`docs/ja/workflows.md`](docs/ja/workflows.md)を参照してください。
46
+
47
+ ## JavaScript API
48
+
49
+ ```js
50
+ import {readFile} from 'node:fs/promises';
51
+
52
+ import {
53
+ buildSb3,
54
+ bundleExtensions,
55
+ createDeterministicSb3,
56
+ extensionIntegrity,
57
+ extensionStatus,
58
+ importSb3,
59
+ migrateExtensionId,
60
+ planExtensionIdMigration,
61
+ syncExtensions,
62
+ unbundleSb3,
63
+ unbundleExtensions,
64
+ updateExtensions,
65
+ validateSb3Source,
66
+ } from '@kubohiroya/sb3-toolchain';
67
+
68
+ await importSb3({
69
+ inputPath: 'tmp/project.sb3',
70
+ outputDirectory: 'app',
71
+ });
72
+
73
+ await validateSb3Source('app');
74
+
75
+ await buildSb3({
76
+ sourceDirectory: 'app',
77
+ outputPath: 'dist/project.sb3',
78
+ });
79
+
80
+ const {archive} = await createDeterministicSb3('app');
81
+
82
+ const integrity = extensionIntegrity(await readFile('app/extensions/example.js'));
83
+
84
+ const statuses = await extensionStatus('app');
85
+ const migration = await planExtensionIdMigration({
86
+ sourceDirectory: 'app',
87
+ fromId: 'oldId',
88
+ toId: 'newid',
89
+ });
90
+ await migrateExtensionId({
91
+ sourceDirectory: 'app',
92
+ fromId: 'oldId',
93
+ toId: 'newid',
94
+ yes: true,
95
+ });
96
+ await syncExtensions({sourceDirectory: 'app', yes: true});
97
+ await updateExtensions({
98
+ sourceDirectory: 'app',
99
+ extensionId: 'oldId',
100
+ migrateToId: 'newid',
101
+ sourceArtifact: 'dist/newid.js',
102
+ apiManifestArtifact: 'dist/newid.manifest.json',
103
+ yes: true,
104
+ });
105
+ // After reviewing a reported breaking API change, opt in explicitly:
106
+ await updateExtensions({sourceDirectory: 'app', allowBreakingApi: true, yes: true});
107
+ await bundleExtensions({
108
+ sourceDirectory: 'app',
109
+ bundleId: 'projectbundle',
110
+ bundleName: 'Project Extension Bundle',
111
+ extensionIds: ['extensionone', 'extensiontwo'],
112
+ yes: true,
113
+ });
114
+ await unbundleExtensions({
115
+ sourceDirectory: 'app',
116
+ bundleId: 'projectbundle',
117
+ yes: true,
118
+ });
119
+ await unbundleSb3({
120
+ inputPath: 'dist/project.sb3',
121
+ outputPath: 'dist/project.unbundled.sb3',
122
+ bundleId: 'projectbundle',
123
+ yes: true,
124
+ });
125
+ ```
126
+
127
+ ## ドキュメント
128
+
129
+ - [`docs/ja/workflows.md`](docs/ja/workflows.md): SB3ソースと機能拡張を管理するワークフロー
130
+ - [`docs/ja/source-format-v1.md`](docs/ja/source-format-v1.md): 展開ソース形式と決定的出力
131
+ - [`docs/ja/extension-id-migration.md`](docs/ja/extension-id-migration.md): プロジェクトで使用中の機能拡張IDの移行
132
+ - [`docs/ja/extension-api-compatibility.md`](docs/ja/extension-api-compatibility.md): 機能拡張更新時の任意の静的API互換性検査
133
+ - [`docs/ja/extension-bundles.md`](docs/ja/extension-bundles.md): 1つの権限単位への静的bundleと可逆的なunbundle
134
+
135
+ ## 開発
136
+
137
+ ```bash
138
+ pnpm install
139
+ pnpm check
140
+ ```
141
+
142
+ ## ライセンス
143
+
144
+ [Mozilla Public License 2.0](LICENSE)
145
+
146
+ この実装は、[`kubohiroya/tmpose-kamishibai`](https://github.com/kubohiroya/tmpose-kamishibai)
147
+ 向けに開発された一般的なSB3ソース管理機構を、プロジェクト固有およびTMPose固有の処理から分離したものです。
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # sb3-toolchain
2
2
 
3
+ [日本語](README.ja.md)
4
+
3
5
  A Node.js toolchain for managing Scratch 3 and TurboWarp `.sb3` projects as Git-diffable
4
6
  expanded sources and rebuilding bit-for-bit identical SB3 files from the same input.
5
7
 
@@ -16,9 +18,6 @@ expanded sources and rebuilding bit-for-bit identical SB3 files from the same in
16
18
  - Protect existing output through transactional replacement and rollback
17
19
  - Provide both a CLI and a JavaScript API
18
20
 
19
- TMPose kamishibai script conversion, project-specific data, and web application generation with
20
- TurboWarp Packager are outside the scope of this package.
21
-
22
21
  ## Requirements
23
22
 
24
23
  - Node.js 22.12.0 or later
@@ -29,7 +28,7 @@ TurboWarp Packager are outside the scope of this package.
29
28
  Pin the verified npm version for reproducible installation.
30
29
 
31
30
  ```bash
32
- pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.3.0
31
+ pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.4.0
33
32
  ```
34
33
 
35
34
  ## Quick start
@@ -1,5 +1,7 @@
1
1
  # Static bundles for embedded extensions
2
2
 
3
+ [日本語版](ja/extension-bundles.md)
4
+
3
5
  When a newly opened SB3 contains several unsandboxed extensions, TurboWarp asks for permission to
4
6
  run each extension. A static bundle keeps the individual extensions in the expanded source but
5
7
  transforms only the generated SB3 into one composite extension, reducing the permission unit to
@@ -227,11 +229,12 @@ each member's `getInfo().blocks`. In the TurboWarp Editor palette, each group be
227
229
  LABEL heading in this form:
228
230
 
229
231
  ```text
230
- ◆ Bundled extension: <name> [<memberId>] ◆
232
+ ◆ <name> [<memberId>] ◆
231
233
  ```
232
234
 
233
- Two consecutive `---` separators divide member groups. A generated LABEL also carries the following
234
- machine-readable metadata:
235
+ Putting the member name first keeps it visible in TurboWarp's narrow palette. Two consecutive `---`
236
+ separators divide member groups. A generated LABEL also carries the following machine-readable
237
+ metadata:
235
238
 
236
239
  ```js
237
240
  {
@@ -242,6 +245,24 @@ machine-readable metadata:
242
245
  }
243
246
  ```
244
247
 
248
+ When a member's `getInfo()` returns a non-empty string [`docsURI`](https://docs.turbowarp.org/development/extensions/assorted-apis#docsuri),
249
+ the bundle inserts an `Open Documentation` button immediately after that member's heading. It uses TurboWarp's native
250
+ `OPEN_EXTENSION_DOCS` callback, so it preserves the normal `docsURI` behavior instead of delegating
251
+ to extension code. The generated button carries separate metadata and safely XML-escapes the URI:
252
+
253
+ ```js
254
+ {
255
+ sb3Toolchain: {
256
+ docsURI,
257
+ kind: 'bundle-member-docs',
258
+ memberId,
259
+ },
260
+ }
261
+ ```
262
+
263
+ No button is inserted for a member without `docsURI`. Member-provided XML blocks remain unsupported;
264
+ the tool generates only this narrowly defined documentation button XML.
265
+
245
266
  LABEL entries and separators originally defined by a member are preserved unchanged and in their
246
267
  original positions. The decorated bundle heading and wider double separator therefore remain
247
268
  visually distinct from an original heading or ordinary separator. A tool can identify the generated
@@ -252,14 +273,15 @@ The resulting palette has this visual hierarchy:
252
273
 
253
274
  ```text
254
275
  ┌─ Project Extension Bundle ─────────────────────────────┐
255
- │ ◆ Bundled extension: Alpha Tools [alpha] ◆ │ ← generated heading
276
+ │ ◆ Alpha Tools [alpha] ◆ │ ← generated heading
277
+ │ Open Documentation │ ← generated docsURI button
256
278
  │ alpha block 1 │
257
279
  │ Alpha original heading │ ← original LABEL
258
280
  │ │ ← original separator
259
281
  │ alpha block 2 │
260
282
  │ │
261
283
  │ │ ← generated double separator
262
- │ ◆ Bundled extension: Beta Tools [beta] ◆ │ ← generated heading
284
+ │ ◆ Beta Tools [beta] ◆ │ ← generated heading
263
285
  │ beta block 1 │
264
286
  └────────────────────────────────────────────────────────┘
265
287
  ```
@@ -1,5 +1,7 @@
1
1
  # Migrating embedded extension IDs
2
2
 
3
+ [日本語版](ja/extension-id-migration.md)
4
+
3
5
  TurboWarp stores the IDs of loaded extensions in project opcodes and monitors. `extensions migrate-id`
4
6
  does not perform a global string replacement. It changes only references whose meaning is defined by
5
7
  SB3 source format v1.
@@ -0,0 +1,449 @@
1
+ # 埋め込み機能拡張の静的bundle
2
+
3
+ [English](../extension-bundles.md)
4
+
5
+ 新しく開いたSB3に複数のunsandboxed機能拡張が含まれていると、TurboWarpは各機能拡張の実行許可を求めます。
6
+ 静的bundleは個別機能拡張を展開ソースに保持しながら、生成SB3だけを1つの複合機能拡張へ変換し、権限単位を
7
+ 1つの機能拡張にまとめます。
8
+
9
+ ## 概要
10
+
11
+ ```mermaid
12
+ flowchart LR
13
+ subgraph Source["展開ソース(信頼できる情報源)"]
14
+ Project["project.source.json<br/>元のopcode"]
15
+ Alpha["extensions/alpha.js"]
16
+ Beta["extensions/beta.js"]
17
+ end
18
+
19
+ Build["sb3-toolchain build"]
20
+
21
+ subgraph Output["生成されたbundle済みSB3"]
22
+ BundledProject["project.json<br/>名前空間化されたopcode"]
23
+ Composite["1つの複合機能拡張<br/>1回のregister()呼び出し"]
24
+ Capsule["復元カプセル<br/>元の機能拡張データ"]
25
+ end
26
+
27
+ TurboWarp["TurboWarp Editor<br/>1回の権限確認"]
28
+
29
+ Project --> Build
30
+ Alpha --> Build
31
+ Beta --> Build
32
+ Build --> BundledProject
33
+ Build --> Composite
34
+ Build --> Capsule
35
+ BundledProject --> TurboWarp
36
+ Composite --> TurboWarp
37
+ ```
38
+
39
+ 展開ソースには、常に個別機能拡張が保持されます。bundleによって変わるのは生成SB3だけです。安全条件を満たす
40
+ 間は、復元カプセルによって生成成果物を元に戻せます。
41
+
42
+ ## 解決する問題
43
+
44
+ TurboWarpは、読み込んだカスタム機能拡張ごとにunsandboxed実行の許可を与えます。そのため、3つすべてが
45
+ 1つのプロジェクトとして保守・配布されていても、3つの埋め込み機能拡張を含むプロジェクトでは3回の確認が
46
+ 表示されます。bundleが変更するのは読み込みの境界であり、セキュリティ上の判断そのものではありません。
47
+
48
+ ```mermaid
49
+ flowchart LR
50
+ subgraph Before["bundleなし"]
51
+ BeforeSB3["SB3"] --> PromptA["機能拡張Aを許可?"]
52
+ PromptA --> PromptB["機能拡張Bを許可?"]
53
+ PromptB --> PromptC["機能拡張Cを許可?"]
54
+ PromptC --> RunBefore["プロジェクトを実行"]
55
+ end
56
+
57
+ subgraph After["静的bundleあり"]
58
+ AfterSB3["SB3"] --> BundlePrompt["プロジェクトbundleを許可?"]
59
+ BundlePrompt --> Members["機能拡張A + B + C"]
60
+ Members --> RunAfter["プロジェクトを実行"]
61
+ end
62
+ ```
63
+
64
+ ユーザーは引き続きunsandboxed JavaScriptを確認し、許可します。生成SB3が公開する複合機能拡張IDと埋め込み
65
+ 機能拡張URLが1つになるため、TurboWarpが許可して読み込むカスタム機能拡張も1つになる点が異なります。
66
+
67
+ ### この機能で行うこと、行わないこと
68
+
69
+ | この機能で行うこと | この機能で行わないこと |
70
+ | ---------------------------------------------------- | ------------------------------------------------ |
71
+ | 複数メンバーから1つの複合ランタイム機能拡張を作成 | TurboWarpの権限確認を無効化または回避 |
72
+ | 生成プロジェクトの参照を衝突しない名前空間へ書き換え | 信頼できる情報源であるプロジェクトを直接書き換え |
73
+ | 各メンバーの元の実装を保持して処理を委譲 | すべてのメンバークラスを手作業で1クラスへ平坦化 |
74
+ | SB3を直接unbundleするための復元データを埋め込み | 任意の動的な機能拡張コードに対する互換性を保証 |
75
+ | 安全に分類できない変換を拒否 | ビルド中に機能拡張JavaScriptを実行 |
76
+
77
+ ## 内部アーキテクチャ
78
+
79
+ bundle処理は、ビルド時とランタイムの層に分かれます。ビルド時には機能拡張JavaScriptを実行せず、データを
80
+ 検証して書き換えます。ランタイムでは、生成したwrapperで各メンバーの登録を捕捉し、メタデータを統合して、
81
+ 呼び出しを委譲します。
82
+
83
+ ```mermaid
84
+ flowchart TB
85
+ subgraph BuildTime["ビルド時:Node.jsツールチェーン"]
86
+ Config["extensionBundles設定"]
87
+ Sources["個別メンバーのJavaScript"]
88
+ SourceProject["元のproject.source.json"]
89
+ Validator["静的契約バリデーター"]
90
+ Generator["bundleソースジェネレーター"]
91
+ Rewriter["プロジェクト参照リライター"]
92
+ BundleJS["生成された複合JavaScript"]
93
+ BundledProject["生成されたproject.json"]
94
+ Archive["決定的SB3アーカイブ"]
95
+
96
+ Config --> Validator
97
+ Sources --> Validator
98
+ Validator --> Generator
99
+ SourceProject --> Rewriter
100
+ Config --> Rewriter
101
+ Generator --> BundleJS
102
+ Rewriter --> BundledProject
103
+ BundleJS --> Archive
104
+ BundledProject --> Archive
105
+ end
106
+
107
+ subgraph Runtime["ランタイム:TurboWarp"]
108
+ Manager["機能拡張マネージャー"]
109
+ Wrapper["生成されたbundle wrapper"]
110
+ Captured["捕捉したメンバーインスタンス"]
111
+ Composite["StaticExtensionBundle"]
112
+ Palette["1つのパレットカテゴリ"]
113
+ VM["Scratch VMの実行"]
114
+
115
+ Manager -->|"1つのdata URLを読み込む"| Wrapper
116
+ Wrapper -->|"Scratch proxyでメンバーを実行"| Captured
117
+ Captured -->|"getInfo()と委譲処理を合成"| Composite
118
+ Composite -->|"1回だけ登録"| Manager
119
+ Manager --> Palette
120
+ VM -->|"名前空間化されたopcode"| Composite
121
+ Composite -->|"委譲"| Captured
122
+ end
123
+
124
+ Archive --> Manager
125
+ ```
126
+
127
+ ### 生成JavaScriptの構造
128
+
129
+ 生成されるdata URLは、次の層で構成される自己完結したclassic機能拡張スクリプトです。
130
+
131
+ ```text
132
+ projectbundle.js
133
+ ├── 人が読めるbundleヘッダー
134
+ │ └── メンバーの名前、ID、作者、説明、ライセンス
135
+ ├── ランタイムアダプター
136
+ │ ├── 各メンバーのScratch proxy
137
+ │ ├── 同期register()の捕捉
138
+ │ ├── opcode、メニュー、カスタムフィールド、hatの名前空間
139
+ │ └── グローバルおよびターゲットストレージの別名
140
+ ├── 元のメンバーソースA
141
+ ├── 元のメンバーソースB
142
+ ├── StaticExtensionBundle
143
+ │ ├── 統合されたgetInfo()
144
+ │ ├── 生成されたパレット見出しとseparator
145
+ │ └── 捕捉したメンバーインスタンスへ委譲するhandler
146
+ ├── 実際のScratch.extensions.register()呼び出し1回
147
+ └── SB3-Toolchain-Reversible-Bundle-v1復元カプセル
148
+ ```
149
+
150
+ 元のスクリプトは、ランタイムで通常の初期化コードを引き続き実行します。各スクリプトの
151
+ `Scratch.extensions.register()`呼び出しはTurboWarpへ送られず、メンバー固有のScratch proxyに捕捉されます。
152
+ すべてのメンバーがちょうど1回ずつ登録された後、wrapperは実際のAPIに複合機能拡張を登録します。
153
+
154
+ ### ランタイム呼び出しフロー
155
+
156
+ ```mermaid
157
+ sequenceDiagram
158
+ participant VM as TurboWarp VM
159
+ participant W as Bundle wrapper
160
+ participant A as メンバーalpha
161
+ participant B as メンバーbeta
162
+ participant C as 複合機能拡張
163
+
164
+ VM->>W: projectbundleのdata URLを読み込む
165
+ W->>A: proxyされたScratchで実行
166
+ A-->>W: register(alphaインスタンス)を捕捉
167
+ W->>B: proxyされたScratchで実行
168
+ B-->>W: register(betaインスタンス)を捕捉
169
+ W->>C: 統合getInfo()と委譲処理を構築
170
+ W->>VM: compositeを1回登録
171
+
172
+ VM->>C: alpha__doSomething(args, util)を呼び出す
173
+ C->>A: 元のdoSomething(args, util)を呼び出す
174
+ A-->>C: 結果
175
+ C-->>VM: 結果
176
+
177
+ A->>W: startHats("alpha_whenReady")
178
+ W->>VM: startHats("projectbundle_alpha__whenReady")
179
+ ```
180
+
181
+ ### データ変換
182
+
183
+ | 対象 | bundle前 | 生成されたbundle済みSB3 |
184
+ | ------------------------------ | ---------------------------------- | --------------------------------------------- |
185
+ | 読み込まれる機能拡張ID | `alpha`、`beta` | `projectbundle` |
186
+ | 埋め込みdata URL | メンバーごとに1つ | 1つの複合data URL |
187
+ | メンバー`getInfo()`のopcode | `doSomething` | `alpha__doSomething` |
188
+ | 保存されるプロジェクトopcode | `alpha_doSomething` | `projectbundle_alpha__doSomething` |
189
+ | メニューとカスタムフィールド名 | メンバー内の名前 | `memberId__`名前空間 |
190
+ | `startHats()`のopcode | `alpha_whenReady` | `projectbundle_alpha__whenReady` |
191
+ | 機能拡張ストレージ | `storage.alpha`、`storage.beta` | `storage.projectbundle.components.alpha/beta` |
192
+ | ブロックIDとグラフリンク | 元のIDと`next`/`parent`/`inputs` | 変更なし |
193
+
194
+ この分離により、保存済みプロジェクトがTurboWarpの期待する複合機能拡張IDを使用する一方、既存スクリプトは元の
195
+ メソッドを呼び出し続けられます。
196
+
197
+ ## 互換性と可逆性
198
+
199
+ bundle設定は`embedded-extensions.json`だけに追加されます。信頼できる情報源である次のデータは変更されません。
200
+
201
+ - `extensions/<extensionId>.js`内の元のJavaScript
202
+ - `embedded-extensions.json`内の個別機能拡張エントリと`source`来歴
203
+ - `project.source.json`内の元の機能拡張ID、ブロックとmonitorのopcode、機能拡張ストレージ
204
+
205
+ `check`と`extensions status|sync|update`は、引き続き個別機能拡張を検証・更新します。`build`だけが
206
+ メモリ上の`project.json`と埋め込みJavaScriptをbundle表現へ変換します。元のファイルを削除するモードは
207
+ ありません。
208
+
209
+ 安全に変換できない機能拡張は、動作を変えてbundleするのではなく拒否されます。現在の静的bundle契約では、
210
+ 次のすべてを満たす必要があります。
211
+
212
+ - すべてのメンバーがExtension Gallery形式の`Name`、`ID`、`Description`、`By`、`License`ヘッダーを持つ
213
+ - ヘッダーID、マニフェストID、ランタイム`getInfo().id`が同一である
214
+ - すべてのメンバーが`Scratch.extensions.register`をちょうど1回かつ同期的に呼び出すclassicスクリプトである
215
+ - XMLブロックを使用するメンバーがない
216
+ - ブロック、monitor、動的ブロックメタデータ以外に未分類のopcode参照が残らない
217
+
218
+ bundleは、通常のcommand、reporter、boolean、event、button、label、静的および動的メニュー、
219
+ カスタムフィールド、グローバルおよびターゲット機能拡張ストレージを名前空間化します。子機能拡張からの
220
+ `runtime.startHats`呼び出しもbundle済みopcodeへ変換します。
221
+
222
+ bundleは、マニフェストの`members`順と、各メンバーの`getInfo().blocks`内のブロック定義順を保持します。
223
+ TurboWarp Editorのパレットでは、各グループが次の形式の装飾済みLABEL見出しから始まります。
224
+
225
+ ```text
226
+ ◆ <name> [<memberId>] ◆
227
+ ```
228
+
229
+ メンバー名を先頭へ置くことで、幅の狭いTurboWarpパレットでも名前が見えるようにします。メンバーグループは、
230
+ 連続する2つの`---` separatorで区切られます。生成LABELには、次の機械可読メタデータも含まれます。
231
+
232
+ ```js
233
+ {
234
+ sb3Toolchain: {
235
+ kind: 'bundle-member-heading',
236
+ memberId,
237
+ },
238
+ }
239
+ ```
240
+
241
+ メンバーの`getInfo()`が空でない文字列[`docsURI`](https://docs.turbowarp.org/development/extensions/assorted-apis#docsuri)を返す場合、
242
+ bundleはそのメンバー見出しの直後に`Open Documentation`ボタンを挿入します。機能拡張コードへの委譲ではなく、TurboWarp標準の
243
+ `OPEN_EXTENSION_DOCS` callbackを使用するため、通常の`docsURI`と同じ動作を保持します。生成ボタンには別の
244
+ メタデータを付け、URIを安全にXML escapeします。
245
+
246
+ ```js
247
+ {
248
+ sb3Toolchain: {
249
+ docsURI,
250
+ kind: 'bundle-member-docs',
251
+ memberId,
252
+ },
253
+ }
254
+ ```
255
+
256
+ `docsURI`を持たないメンバーにはボタンを追加しません。メンバー自身が定義するXMLブロックは引き続き非対応で、
257
+ ツールが生成するXMLはこの限定されたドキュメントボタンだけです。
258
+
259
+ メンバーが元から定義しているLABELエントリとseparatorは、位置も含めて変更せず保持されます。そのため、
260
+ 装飾済みbundle見出しと幅の広い二重separatorは、元の見出しや通常のseparatorと視覚的に区別できます。
261
+ ツールは`sb3Toolchain`メタデータで生成見出しを識別し、その直前にある2つのseparatorをbundleグループ境界として
262
+ 扱えます。
263
+
264
+ 生成されるパレットの視覚的階層は次のようになります。
265
+
266
+ ```text
267
+ ┌─ Project Extension Bundle ─────────────────────────────┐
268
+ │ ◆ Alpha Tools [alpha] ◆ │ ← 生成見出し
269
+ │ Open Documentation │ ← 生成されたdocsURIボタン
270
+ │ alpha block 1 │
271
+ │ Alpha original heading │ ← 元のLABEL
272
+ │ │ ← 元のseparator
273
+ │ alpha block 2 │
274
+ │ │
275
+ │ │ ← 生成された二重separator
276
+ │ ◆ Beta Tools [beta] ◆ │ ← 生成見出し
277
+ │ beta block 1 │
278
+ └────────────────────────────────────────────────────────┘
279
+ ```
280
+
281
+ ## bundleの設定
282
+
283
+ まずdry runで、選択したメンバー、ヘッダーメタデータ、衝突、opcode参照を検証します。
284
+
285
+ ```bash
286
+ sb3-toolchain extensions bundle app \
287
+ --id projectbundle \
288
+ --name "Project Extension Bundle" \
289
+ extensionone extensiontwo
290
+ ```
291
+
292
+ メンバーIDを省略すると、まだ別のbundleに割り当てられていないすべての埋め込み機能拡張が選択されます。
293
+ bundleには少なくとも2つのメンバーが必要です。適用前に結果を確認してください。
294
+
295
+ ```bash
296
+ sb3-toolchain extensions bundle app \
297
+ --id projectbundle \
298
+ --name "Project Extension Bundle" \
299
+ extensionone extensiontwo \
300
+ --yes
301
+ sb3-toolchain check app
302
+ sb3-toolchain build app --output dist/project.sb3
303
+ ```
304
+
305
+ 生成SB3では、メンバーのopcodeが次のように変換されます。
306
+
307
+ ```text
308
+ 元の機能拡張のgetInfo() opcode: doSomething
309
+ bundleのgetInfo() opcode: extensionone__doSomething
310
+ 元のproject.json opcode: extensionone_doSomething
311
+ bundle済みproject.json opcode: projectbundle_extensionone__doSomething
312
+ ```
313
+
314
+ bundleは各元opcodeに`memberId + "__"`を加えるため、異なるメンバーの同一opcodeが衝突することはありません。
315
+ メンバーIDは`[a-z0-9]+`に制限されるため、区切りは明確です。同じメンバー内で変換後のopcodeが衝突する場合は、
316
+ bundleの読み込みを拒否します。
317
+
318
+ `extensions`と`extensionURLs`には`projectbundle`だけが現れ、生成JavaScriptは
319
+ `Scratch.extensions.register`を1回呼び出します。そのJavaScriptの先頭コメントには全メンバーの名前、ID、
320
+ 作者、説明、ライセンスが列挙され、ユーザーは権限を許可する前に確認できます。
321
+
322
+ JavaScriptの末尾には`SB3-Toolchain-Reversible-Bundle-v1`復元カプセルが含まれます。カプセルは各メンバーの
323
+ 元のdata URL、メンバー順、元の`extensions`と`extensionURLs`の順序を記録します。
324
+
325
+ ## 展開ソースからの復元
326
+
327
+ 利用可能な成果物に応じて復元経路を選択します。
328
+
329
+ ```mermaid
330
+ flowchart TD
331
+ Start{"何を利用できますか?"}
332
+ Source["展開ソースディレクトリ"]
333
+ SB3["bundle済みSB3のみ"]
334
+ SourceCommand["extensions unbundle SOURCE_DIR"]
335
+ ArchiveCommand["extensions unbundle INPUT.sb3<br/>--output OUTPUT.sb3"]
336
+ Rebuild["保持されたproject.source.jsonと<br/>メンバーJSから再ビルド"]
337
+ Recover["復元カプセルを検証して<br/>プロジェクト変換を逆変換"]
338
+ Restored["個別機能拡張を持つSB3"]
339
+
340
+ Start -->|"信頼できるソース"| Source
341
+ Start -->|"配布成果物"| SB3
342
+ Source --> SourceCommand --> Rebuild --> Restored
343
+ SB3 --> ArchiveCommand --> Recover --> Restored
344
+ ```
345
+
346
+ まずdry runでunbundle計画を確認し、次に`--yes`を渡してbundle設定を削除します。
347
+
348
+ ```bash
349
+ sb3-toolchain extensions unbundle app projectbundle
350
+ sb3-toolchain extensions unbundle app projectbundle --yes
351
+ sb3-toolchain check app
352
+ sb3-toolchain build app --output dist/project.sb3 --yes
353
+ ```
354
+
355
+ 元のJavaScriptとプロジェクト表現が保持されているため、次のビルドでは個別IDとdata URLを復元し、ブロック、
356
+ 動的ブロックメタデータ、monitorのopcodeを元の値で再生成します。この形式のunbundleでは、配布SB3の
357
+ リバースエンジニアリングを試みません。保存済み`project.source.json`と個別JavaScriptからプロジェクトを
358
+ 再生成するため、推測によるopcode逆変換で情報が失われることはありません。bundle設定中に
359
+ `extensions update`を実行していた場合は、更新後の個別JavaScriptを使用してプロジェクトを復元します。
360
+
361
+ 展開ソースを信頼できる情報源として扱ってください。生成したbundle済みSB3を、同じ信頼できるソースへ
362
+ 再importしないでください。新しいディレクトリへimportすると、配布用の複合機能拡張が1つの通常機能拡張として
363
+ 展開され、個別の来歴は復元できません。既存の信頼できるソースを誤って選択した場合でも、通常のGit差分保護と
364
+ 置換確認が適用されます。
365
+
366
+ ## bundle済みSB3の直接復元
367
+
368
+ 復元カプセルを含むbundle済みSB3は、展開ソースがなくてもunbundleできます。`--yes`を指定しない限り、
369
+ コマンドはdry runです。
370
+
371
+ ```bash
372
+ sb3-toolchain extensions unbundle \
373
+ dist/project.sb3 projectbundle \
374
+ --output dist/project.unbundled.sb3
375
+ sb3-toolchain extensions unbundle \
376
+ dist/project.sb3 projectbundle \
377
+ --output dist/project.unbundled.sb3 \
378
+ --yes
379
+ ```
380
+
381
+ 直接unbundleでは次のすべてを復元します。
382
+
383
+ - bundle opcodeを`memberId_originalOpcode`へ戻し、ブロックID、`next`、`parent`、`inputs`は変更しない
384
+ - 通常ブロック、動的ブロックメタデータ、monitorのopcode
385
+ - bundleストレージの`components`を、元のメンバーIDをキーとするストレージへ変換
386
+ - 個別メンバーのdata URLと、元の`extensions`および`extensionURLs`の順序
387
+ - アセットエントリとそのバイト内容
388
+
389
+ bundle後にTurboWarpでブロックを追加、削除、移動できます。追加されたブロックも、opcodeが
390
+ `bundleId_memberId__originalOpcode`形式なら復元できます。複数のbundleを含むSB3は、すべてのbundleが有効な
391
+ 復元カプセルを持ち、メンバー集合が重複していなければ、任意の順序で1つずつunbundleできます。
392
+
393
+ ### 直接unbundleできない条件
394
+
395
+ ```mermaid
396
+ flowchart TD
397
+ Input["bundle済みSB3"]
398
+ Capsule{"有効な復元カプセル?"}
399
+ Order{"機能拡張IDの集合と<br/>順序が一致?"}
400
+ Mapping{"すべてのbundle opcodeが<br/>ちょうど1つのメンバーに対応?"}
401
+ Storage{"ストレージが衝突のない<br/>可逆形式1?"}
402
+ Write["unbundle済みSB3を書き込む"]
403
+ Refuse["安全に拒否して<br/>出力を変更しない"]
404
+
405
+ Input --> Capsule
406
+ Capsule -->|"はい"| Order
407
+ Capsule -->|"いいえ"| Refuse
408
+ Order -->|"はい"| Mapping
409
+ Order -->|"いいえ"| Refuse
410
+ Mapping -->|"はい"| Storage
411
+ Mapping -->|"いいえ"| Refuse
412
+ Storage -->|"はい"| Write
413
+ Storage -->|"いいえ"| Refuse
414
+ ```
415
+
416
+ 次のいずれかの条件に該当する場合、ツールは推測せず、出力を変更せずに操作を拒否します。
417
+
418
+ - 対象data URLに`SB3-Toolchain-Reversible-Bundle-v1`カプセルがない。復元カプセル導入前、別のツール、
419
+ または手作業でbundleが生成された場合が該当する
420
+ - bundle data URLまたはカプセルが削除、破損、重複している、形式バージョンが未対応、またはbundle ID、
421
+ メンバーID、元のJavaScriptヘッダーIDが一致しない
422
+ - bundle後に`project.extensions`または`extensionURLs`内のID集合や順序が変わった。たとえば別の機能拡張を
423
+ 追加または削除すると、元のメンバーの正確な挿入位置を安全に推測できない
424
+ - `bundleId_`で始まるopcodeをメンバーの`memberId__`名前空間へ割り当てられない、または通常ブロック、
425
+ 動的ブロックメタデータ、monitor以外に未分類のbundle opcode参照が残っている
426
+ - bundleストレージが`{formatVersion: 1, components: {...}}`ではない、未知のメンバーまたは追加のbundleレベル
427
+ フィールドを含む、あるいは復元するメンバーIDをすでに使用するストレージと衝突する
428
+ - 有効な可逆bundle間でメンバーが重複している
429
+ - ZIPが空、`project.json`が欠落または無効、エントリ名が安全でない、あるいはエントリ順を安全に保持できない
430
+
431
+ 展開ソースを利用できる場合、これらの条件があっても、ソースを使用する`extensions unbundle SOURCE_DIR`
432
+ ワークフローでbundle設定を削除してプロジェクトを再ビルドできます。復元カプセルを持たない古い生成SB3は、
433
+ そのSB3だけから直接逆変換することはできません。
434
+
435
+ 直接unbundleではアセットのバイト列を保持しますが、ZIPを決定的に再圧縮します。入力ZIPメタデータ、
436
+ エントリタイムスタンプ、アーカイブコメントのバイト単位での同一性は保持しません。
437
+
438
+ ## 検証
439
+
440
+ 静的検証では、ブラウザAPI、カメラ、renderer、機能拡張間の暗黙的な依存関係に対する互換性を証明できません。
441
+ bundle前後に同じプロジェクトレベルの自動テストを実行し、生成SB3を新しいTurboWarpセッションで開いて、
442
+ 次のすべてを確認してください。
443
+
444
+ - unsandboxed実行の確認が1回だけ表示される
445
+ - green flagの動作と、block、reporter、hat、monitor、menuの結果が変わらない
446
+ - カメラ、ネットワーク、ファイル選択、rendererアクセスなど、プロジェクトが使用する権限経路が動作する
447
+ - TurboWarpで再保存したSB3が機能拡張ストレージを保持し、再読み込み後も動作する
448
+
449
+ 互換性を検証できないメンバーはbundleから除外し、個別機能拡張として保持してください。
@@ -0,0 +1,69 @@
1
+ # 埋め込み機能拡張IDの移行
2
+
3
+ [English](../extension-id-migration.md)
4
+
5
+ TurboWarpは読み込んだ機能拡張のIDをプロジェクトのopcodeとmonitorに保存します。
6
+ `extensions migrate-id`はグローバルな文字列置換を行いません。SB3ソース形式v1で意味が定義されている参照だけを
7
+ 変更します。
8
+
9
+ ## dry runと適用
10
+
11
+ 単独の移行コマンドは、既定ではdry runです。
12
+
13
+ ```bash
14
+ sb3-toolchain extensions migrate-id app --from twOld --to newext
15
+ ```
16
+
17
+ 分類済みの変更件数と`Unclassified`参照を確認します。移行を適用する前に、新しいIDを宣言するJavaScript成果物を
18
+ `extensions/twOld.js`へ配置します。
19
+
20
+ ```bash
21
+ sb3-toolchain extensions migrate-id app --from twOld --to newext --yes
22
+ ```
23
+
24
+ 新しいIDはTurboWarp公式の`[a-z0-9]+`形式でなければなりません。新しいIDがマニフェスト、
25
+ `extensionURLs`、`project.extensions`のいずれかにすでに存在する場合、移行は衝突として拒否されます。
26
+
27
+ ## 分類済み参照
28
+
29
+ ツールは次の参照を変更します。
30
+
31
+ - `project.source.json`の`extensions[]`にある完全一致のID
32
+ - `extensionURLs`の完全一致するキーと埋め込み機能拡張の値
33
+ - `targets[*].blocks[*].opcode`の完全一致する`<oldId>_`接頭辞
34
+ - 通常のブロックスキーマを使用するメニューブロックのopcode
35
+ - `monitors[*].opcode`の完全一致する`<oldId>_`接頭辞
36
+ - `embedded-extensions.json`の`id`と`path`
37
+ - `extensions/<oldId>.js`から`extensions/<newId>.js`へのファイル名変更
38
+
39
+ 変数名、リスト名、ブロックリテラル、メタデータ、別の機能拡張のopcodeに旧IDを含む文字列は変更されません。
40
+ これらは、人が意味を判断できるように、dry run出力へJSON Pointer付きの未分類参照として表示されます。
41
+
42
+ ## GitHub管理対象機能拡張
43
+
44
+ 管理対象機能拡張では、新しいIDを宣言する成果物を上流リポジトリが公開した後、更新と移行を組み合わせる方法を
45
+ 推奨します。
46
+
47
+ ```bash
48
+ sb3-toolchain extensions update app twOld \
49
+ --migrate-id newext \
50
+ --artifact dist/newext.js \
51
+ --api-manifest-artifact dist/newext.manifest.json
52
+ ```
53
+
54
+ 上流のJavaScript成果物パスも変わった場合に限り`--artifact`を指定します。任意で使用しているマニフェストの
55
+ 成果物パスも変わった場合に限り`--api-manifest-artifact`を指定します。ツールは追跡対象のrefを変更不能な
56
+ コミットに解決し、そのコミットから新しい成果物をダウンロードします。ローカルファイルを変更する前に、
57
+ `// ID: newext`を宣言していない成果物、衝突、無効な新IDを拒否します。
58
+
59
+ 管理対象機能拡張が`source.apiManifest`を持つ場合、ツールは同じコミットから候補マニフェストをダウンロードし、
60
+ 明示した旧IDと新IDのトップレベルIDだけを正規化して、残りのすべてのフィールドに通常のAPI互換性ポリシーを
61
+ 適用します。JavaScript、名前を変更したローカルマニフェスト、来歴、指定した場合の両リモート成果物パス、
62
+ 両方のintegrity値を、1回のトランザクションで変更します。詳しくは、
63
+ [`extension-api-compatibility.md`](extension-api-compatibility.md)を参照してください。
64
+
65
+ ## 検証とロールバック
66
+
67
+ ツールは展開ソースディレクトリをトランザクションで置き換える前に、通常のソース検証と候補SB3の決定的ビルドを
68
+ 完了します。置換が失敗した場合は、元のディレクトリを自動的に復元します。merge後にロールバックするには、
69
+ プロジェクトの移行コミットをrevertし、旧ID、成果物、来歴をまとめて元に戻します。
@@ -0,0 +1,190 @@
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
+ 任意の`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
+ - `repository`: `<owner>/<repository>`形式のGitHubリポジトリ
78
+ - `ref`: 更新候補として追跡するブランチ、タグ、またはコミット
79
+ - `resolvedCommit`: 現在のファイルの取得に使用した、小文字40文字のコミットSHA
80
+ - `artifact`: リポジトリルートを基準にしたJavaScript成果物のパス
81
+ - `integrity`: 現在のファイルのSRI形式SHA-256
82
+ - `apiManifest`: 任意で使用するAPI互換性メタデータ
83
+ - `artifact`: 同じGitHubリポジトリを基準にしたAPIマニフェストのパス
84
+ - `path`: 必須のローカルパス`extensions/<extensionId>.manifest.json`
85
+ - `formatVersion`: 対応するマニフェスト形式。現在は`1`
86
+ - `integrity`: インストール済みマニフェストのSRI形式SHA-256
87
+
88
+ 検証とビルドでは、ネットワークへ接続せずに管理対象機能拡張を検証します。
89
+
90
+ - 実ファイルのSHA-256が`integrity`と一致する
91
+ - ファイルの`// ID: <extensionId>`ヘッダーが`id`と一致する
92
+ - リポジトリ、ref、コミット、成果物パスが安全な形式である
93
+ - `apiManifest`が存在する場合、そのJSONスキーマ、ID、形式バージョン、パス、SHA-256が有効である
94
+
95
+ 既存の展開ソースディレクトリへSB3を再importすると、同じIDとパスの`source`メタデータが保持されます。
96
+ importしたファイルが記録済みのハッシュまたはIDと一致しない場合、既存の出力を変更せずにimportを拒否します。
97
+ 新規importでは来歴を推測できないため、`source`は自動作成されません。
98
+
99
+ `extensions sync`は、変更不能な`resolvedCommit`を使用してJavaScriptと任意のAPIマニフェストを
100
+ ダウンロードし、そのIDとハッシュが既存メタデータに一致する場合に限りローカルファイルを復元します。
101
+ `extensions update`はGitHub APIを通じて`ref`を解決し、同じコミットから両方の成果物をダウンロードして、
102
+ 候補APIマニフェストをインストール済み契約と比較します。互換性検査と内容検証が成功した後に限り、
103
+ `resolvedCommit`と両方のintegrity値を更新します。選択したすべてのエントリのダウンロードと検証が完了するまで、
104
+ 展開ソースは変更されません。
105
+
106
+ 機能拡張IDの移行では、マニフェストの`id`と`path`、`project.source.json`内の既知の参照、
107
+ `extensions/<id>.js`を1回のトランザクションで変更します。`extensions update`の一部として管理対象機能拡張を
108
+ 移行する場合は、明示的に指定した`artifact`、`resolvedCommit`、`integrity`も新しい成果物に合わせて更新します。
109
+ 任意のAPIマニフェストは、明示した旧IDと新IDのトップレベルIDを正規化してから比較し、新しいIDで保存して、
110
+ 同じトランザクションで更新します。リモートファイル名も変わる場合は、`--api-manifest-artifact`で
111
+ `source.apiManifest.artifact`を明示的に更新します。
112
+
113
+ APIマニフェストファイルは展開ソースの検証入力であり、SB3アーカイブのエントリではありません。決定的なSB3の
114
+ バイト列は変わりません。マニフェストv1、互換性分類、破壊的変更の明示的な許可、ロールバックについては、
115
+ [`extension-api-compatibility.md`](extension-api-compatibility.md)を参照してください。
116
+
117
+ ### `extensionBundles`
118
+
119
+ 任意の`extensionBundles`配列を追加すると、複数の個別機能拡張を、生成SB3内だけで1つの権限単位にできます。
120
+
121
+ ```json
122
+ {
123
+ "formatVersion": 1,
124
+ "extensions": [
125
+ {
126
+ "id": "extensionone",
127
+ "path": "extensions/extensionone.js",
128
+ "mediaType": "text/javascript",
129
+ "parameters": [],
130
+ "encoding": "base64"
131
+ },
132
+ {
133
+ "id": "extensiontwo",
134
+ "path": "extensions/extensiontwo.js",
135
+ "mediaType": "text/javascript",
136
+ "parameters": [],
137
+ "encoding": "base64"
138
+ }
139
+ ],
140
+ "extensionBundles": [
141
+ {
142
+ "id": "projectbundle",
143
+ "name": "Project Extension Bundle",
144
+ "members": ["extensionone", "extensiontwo"]
145
+ }
146
+ ]
147
+ }
148
+ ```
149
+
150
+ - `id`: TurboWarpの`[a-z0-9]+`形式で、個別機能拡張と衝突しない複合機能拡張ID
151
+ - `name`: 権限確認と機能拡張カテゴリに表示される単一行の名前
152
+ - `members`: 2つ以上の個別機能拡張ID。順序によってブロックとメニューの合成順が決まる。パレットでは、
153
+ メタデータを持つ装飾済みbundle LABEL見出しとグループ間の二重separatorが追加される一方、元の機能拡張の
154
+ LABELエントリとseparatorは変更されない
155
+
156
+ 1つのメンバーを複数のbundleに所属させることはできません。個別エントリ、個別JavaScript、`source`、
157
+ `project.source.json`が引き続き信頼できる情報源です。`build`は各元opcodeに`memberId + "__"`を加え、
158
+ 出力側の`project.json`のopcode、`extensions`、`extensionURLs`、機能拡張ストレージだけをbundle IDに変更します。
159
+ 埋め込まれるbundle JavaScriptのdata URLは1つです。
160
+
161
+ bundle JavaScriptの末尾には、元の個別data URLと機能拡張の順序を格納した形式1の復元カプセルが含まれます。
162
+ 設定を削除するか、そのカプセルを含む生成SB3に対して`extensions unbundle`を実行すると、通常の出力へ
163
+ 復元できます。互換性契約と復元手順については、[`extension-bundles.md`](extension-bundles.md)を参照してください。
164
+
165
+ ## アセット
166
+
167
+ `assets/`には、`project.source.json`から参照されるコスチュームと音声が含まれます。各ファイル名は
168
+ `<assetId>.<dataFormat>`であり、`assetId`は内容のMD5と一致しなければなりません。未参照、欠落、余分な
169
+ ファイルはいずれも検証エラーです。
170
+
171
+ ## 決定的出力
172
+
173
+ - ZIPエントリは`archiveEntries`に従う
174
+ - ZIPタイムスタンプは1980-01-01 00:00:00に固定
175
+ - 圧縮レベルは6に固定
176
+ - `project.json`は末尾に改行を持つ最小JSONとして格納
177
+ - ソース形式のバージョン、入力ファイル、ツールのバージョンが同じなら、同じバイト列を生成
178
+
179
+ ## 安全性
180
+
181
+ - 絶対パス、`\`、空の構成要素、`.`、`..`を含むZIPエントリを拒否
182
+ - ソース入力としてシンボリックリンクと特殊ファイルを拒否
183
+ - ファイルシステムルート、Gitリポジトリルート、その祖先、`.git/`をimport先として拒否
184
+ - 認識できない既存ディレクトリを上書きしない
185
+ - 2段階の明示的な許可なしにGit管理対象の変更を破棄しない
186
+ - 中断された置換のロールバック領域が存在するときは、自動的に上書きしない
187
+ - 管理対象機能拡張のコミット、SHA-256、機能拡張IDをオフラインで検証
188
+ - bundle時に個別JavaScriptと来歴を保持し、互換性を確立できない契約を拒否
189
+ - GitHubからはHTTPSだけで取得し、リダイレクトを拒否してサイズを制限し、ダウンロードしたJavaScriptは
190
+ 決して実行しない
@@ -0,0 +1,249 @@
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をTurboWarpで開き、起動、主要な操作、画像、音声、埋め込み
88
+ 機能拡張の動作を確認してください。
89
+
90
+ ## 管理対象の埋め込み機能拡張
91
+
92
+ `embedded-extensions.json`の`source`オブジェクトには、GitHubリポジトリ、追跡対象ref、解決済みコミット、
93
+ 成果物パス、SHA-256を記録できます。更新時の静的互換性検査に使用するバージョン付きAPIマニフェストも任意で
94
+ 設定できます。完全なスキーマは[`source-format-v1.md`](source-format-v1.md)を参照してください。
95
+
96
+ 機能拡張コマンドの役割は次のとおりです。
97
+
98
+ | コマンド | ネットワーク | refの解決 | メタデータ更新 | 目的 |
99
+ | ----------------------- | ------------ | --------- | -------------- | -------------------------------------- |
100
+ | `extensions status` | あり | あり | なし | 追跡対象refに更新があるか確認 |
101
+ | `extensions sync` | あり | なし | なし | 固定したコミットからファイルを復元 |
102
+ | `extensions update` | あり | あり | あり | 最新のrefコミットへ明示的に更新 |
103
+ | `extensions migrate-id` | なし | なし | ID/参照 | プロジェクトで使用中の機能拡張IDを移行 |
104
+ | `extensions bundle` | なし | なし | bundle設定 | 機能拡張を1つの権限単位へ統合 |
105
+ | `extensions unbundle` | なし | なし | 設定またはSB3 | 個別機能拡張を使用する出力へ復元 |
106
+
107
+ ### 更新の確認
108
+
109
+ ```bash
110
+ sb3-toolchain extensions status app
111
+ ```
112
+
113
+ `status`はローカルファイルを変更しません。追跡対象refが`resolvedCommit`と異なる機能拡張について上流の
114
+ 変更を確認し、更新するかどうかを判断します。
115
+
116
+ ### 固定したコミットからの復元
117
+
118
+ ```bash
119
+ sb3-toolchain extensions sync app
120
+ sb3-toolchain check app
121
+ ```
122
+
123
+ `sync`は変更可能なブランチやタグを解決しません。記録済みの`resolvedCommit`からダウンロードし、
124
+ JavaScriptと任意のAPIマニフェストが記録済みIDおよびSHA-256値に一致する場合に限り、ローカルファイルを
125
+ 置き換えます。
126
+
127
+ ### 追跡対象refの更新
128
+
129
+ ```bash
130
+ sb3-toolchain extensions update app
131
+ sb3-toolchain extensions update app EXTENSION_ID
132
+ sb3-toolchain check app
133
+ git diff -- app
134
+ ```
135
+
136
+ IDを省略すると、管理対象の全機能拡張を1回のトランザクションで更新します。ダウンロードまたは検証が1つでも
137
+ 失敗した場合、ファイルもメタデータも変更しません。
138
+
139
+ `source.apiManifest`が存在する場合、同じ解決済みコミットからJavaScriptとAPIマニフェストをダウンロードします。
140
+ 互換性のある追加は報告されます。ブロックの削除、ブロック種別の変更、引数契約の変更、参照中メニューの削除、
141
+ `acceptReporters`の変更は、インストール前に拒否されます。未参照メニューの削除には互換性があります。
142
+ 報告されたすべてのパスを確認した後、意図的な破壊的更新には両方のフラグが必要です。
143
+
144
+ ```bash
145
+ sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
146
+ ```
147
+
148
+ バージョン付きマニフェスト契約、分類表、既定OFFの動作、ロールバックについては、
149
+ [`extension-api-compatibility.md`](extension-api-compatibility.md)を参照してください。
150
+
151
+ 更新PRでは、`resolvedCommit`、JavaScriptとマニフェストのintegrity、互換性パス、両成果物をまとめて確認し、
152
+ 生成SB3で機能拡張の主要機能をテストします。
153
+
154
+ ## 機能拡張IDの移行
155
+
156
+ 機能拡張IDはopcodeとmonitorに保存されるため、ファイル名やマニフェストだけを手作業で変更しないでください。
157
+ dry runから始め、分類済み参照と未分類参照の両方を確認します。
158
+
159
+ ```bash
160
+ sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID
161
+ ```
162
+
163
+ 新しいIDを宣言するJavaScriptを用意して結果を確認し、適用します。
164
+
165
+ ```bash
166
+ sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID --yes
167
+ sb3-toolchain check app
168
+ git diff -- app
169
+ ```
170
+
171
+ GitHub管理対象機能拡張では、上流成果物の更新とID移行を1回のトランザクションにできます。
172
+
173
+ ```bash
174
+ sb3-toolchain extensions update app OLD_ID \
175
+ --migrate-id NEW_ID \
176
+ --artifact dist/NEW_ID.js
177
+ ```
178
+
179
+ 上流の成果物パスも変わった場合に限り`--artifact`を指定します。影響するスキーマ、衝突検査、未分類参照、
180
+ ロールバックについては、[`extension-id-migration.md`](extension-id-migration.md)を参照してください。
181
+
182
+ ## unsandboxed権限を1回の確認に統合
183
+
184
+ 複数の埋め込み機能拡張を含むプロジェクトでは、静的bundleを任意で使用できます。元のJavaScript、ID、opcode、
185
+ 来歴は変更されず、ビルド出力だけが1つの複合機能拡張へ変換されます。
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
+ プロジェクトレベルの自動テストと実際のTurboWarpでのスモークテストを使用し、bundle前後での同等な動作、
202
+ 1回だけの権限確認、保存後の再読み込み成功を検証します。問題がある場合は、保持されている個別機能拡張へ
203
+ 復元します。
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
+ 展開ソースが利用できない場合でも、このバージョンのツールチェーンで生成したSB3は直接unbundleできます。
213
+ 最初のコマンドはdry runで、`--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
+ 互換性契約、ソースコメント、opcodeとストレージの変換、直接unbundleの制限、再import時の注意事項については、
226
+ [`extension-bundles.md`](extension-bundles.md)を参照してください。
227
+
228
+ ## CIと配布
229
+
230
+ 依存関係のバージョンを固定し、CIで少なくとも次のコマンドを実行します。
231
+
232
+ ```bash
233
+ sb3-toolchain check app
234
+ sb3-toolchain build app --output dist/project.sb3 --yes
235
+ ```
236
+
237
+ プロジェクトレベルの自動テストと手動検証に合格したSB3だけを配布してください。ネットワーク状態が入力になって
238
+ しまうため、リリースビルドの一部として`sync`や`update`を暗黙的に実行しないでください。更新は独立した
239
+ レビュー可能な変更として行い、固定した展開ソースを先にコミットします。
240
+
241
+ ## 失敗時の対応
242
+
243
+ - コマンドが置換を拒否した場合は、再試行する前に`git status`と該当する差分を確認する
244
+ - `.<output-name>.rollback-*`が残っている場合は、復元または削除を決める前に現在の出力と比較する
245
+ - 機能拡張更新が途中で失敗した場合は、再試行する前に`git diff`を確認する
246
+ - merge済み変更はプロジェクトコミットをrevertし、ソース、成果物、来歴をまとめて元に戻す
247
+ - 公開済みSB3を置き換える場合は、プロジェクトのリリースポリシーに従い、履歴を保持する
248
+
249
+ 復旧の近道として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
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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/sb3-toolchain",
3
- "version": "0.3.0",
3
+ "version": "0.4.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",
@@ -25,6 +25,7 @@
25
25
  "docs/",
26
26
  "src/",
27
27
  "README.md",
28
+ "README.ja.md",
28
29
  "LICENSE"
29
30
  ],
30
31
  "publishConfig": {
@@ -34,8 +35,8 @@
34
35
  "packageManager": "pnpm@11.11.0",
35
36
  "scripts": {
36
37
  "lint": "eslint src bin test",
37
- "format": "prettier --check .github bin docs src test package.json README.md tsconfig.json",
38
- "format:write": "prettier --write .github bin docs src test package.json README.md tsconfig.json",
38
+ "format": "prettier --check .github bin docs src test package.json README.md README.ja.md tsconfig.json",
39
+ "format:write": "prettier --write .github bin docs src test package.json README.md README.ja.md tsconfig.json",
39
40
  "typecheck": "tsc --project tsconfig.json",
40
41
  "test": "node --test test/*.test.mjs",
41
42
  "pack:check": "npm pack --dry-run --ignore-scripts",
package/src/constants.js CHANGED
@@ -1,4 +1,4 @@
1
1
  // SPDX-License-Identifier: MPL-2.0
2
2
 
3
3
  export const packageName = '@kubohiroya/sb3-toolchain';
4
- export const packageVersion = '0.3.0';
4
+ export const packageVersion = '0.4.0';
@@ -205,6 +205,14 @@ export function createStaticExtensionBundle(bundle, components, originalProject
205
205
  : opcode;
206
206
  };
207
207
 
208
+ const xmlEscape = (value) => String(value).replace(/[<>&'"]/gu, (character) => ({
209
+ '<': '&lt;',
210
+ '>': '&gt;',
211
+ '&': '&amp;',
212
+ "'": '&apos;',
213
+ '"': '&quot;',
214
+ })[character]);
215
+
208
216
  const installStorageAliases = (storage) => {
209
217
  if (!storage || typeof storage !== 'object') return;
210
218
  const hasBundleStorage = Object.prototype.hasOwnProperty.call(storage, BUNDLE_ID);
@@ -348,8 +356,20 @@ ${loaders}
348
356
  result.blocks.push({
349
357
  blockType: Scratch.BlockType.LABEL,
350
358
  sb3Toolchain: {kind: 'bundle-member-heading', memberId: componentId},
351
- text: '◆ Bundled extension: ' + info.name + ' [' + componentId + '] ◆',
359
+ text: '◆ ' + info.name + ' [' + componentId + '] ◆',
352
360
  });
361
+ if (info.docsURI) {
362
+ const docsURI = String(info.docsURI);
363
+ result.blocks.push({
364
+ blockType: Scratch.BlockType.XML,
365
+ sb3Toolchain: {
366
+ docsURI,
367
+ kind: 'bundle-member-docs',
368
+ memberId: componentId,
369
+ },
370
+ xml: '<button text="Open Documentation" callbackKey="OPEN_EXTENSION_DOCS" callbackData="' + xmlEscape(docsURI) + '"></button>',
371
+ });
372
+ }
353
373
  for (const block of info.blocks || []) {
354
374
  if (block === '---') {
355
375
  result.blocks.push(block);