@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,465 @@
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
+ A->>W: getOpcodeFunction("beta_echo")
181
+ W->>VM: getOpcodeFunction("projectbundle_beta__echo")
182
+ VM-->>A: bundle済みopcodeのhandler
183
+ A->>C: handler(args, util)を呼び出す
184
+ C->>B: 元のecho(args, util)を呼び出す
185
+ B-->>A: 結果またはPromise
186
+ ```
187
+
188
+ ### データ変換
189
+
190
+ | 対象 | bundle前 | 生成されたbundle済みSB3 |
191
+ | ------------------------------ | ---------------------------------- | --------------------------------------------- |
192
+ | 読み込まれる機能拡張ID | `alpha`、`beta` | `projectbundle` |
193
+ | 埋め込みdata URL | メンバーごとに1つ | 1つの複合data URL |
194
+ | メンバー`getInfo()`のopcode | `doSomething` | `alpha__doSomething` |
195
+ | 保存されるプロジェクトopcode | `alpha_doSomething` | `projectbundle_alpha__doSomething` |
196
+ | メニューとカスタムフィールド名 | メンバー内の名前 | `memberId__`名前空間 |
197
+ | `startHats()`のopcode | `alpha_whenReady` | `projectbundle_alpha__whenReady` |
198
+ | `getOpcodeFunction()` | `beta_echo` | `projectbundle_beta__echo` |
199
+ | 機能拡張ストレージ | `storage.alpha`、`storage.beta` | `storage.projectbundle.components.alpha/beta` |
200
+ | ブロックIDとグラフリンク | 元のIDと`next`/`parent`/`inputs` | 変更なし |
201
+
202
+ この分離により、保存済みプロジェクトがTurboWarpの期待する複合機能拡張IDを使用する一方、既存スクリプトは元の
203
+ メソッドを呼び出し続けられます。
204
+
205
+ ## 互換性と可逆性
206
+
207
+ bundle設定は`embedded-extensions.json`だけに追加されます。信頼できる情報源である次のデータは変更されません。
208
+
209
+ - `extensions/<extensionId>.js`内の元のJavaScript
210
+ - `embedded-extensions.json`内の個別機能拡張エントリと`source`来歴
211
+ - `project.source.json`内の元の機能拡張ID、ブロックとmonitorのopcode、機能拡張ストレージ
212
+
213
+ `check`と`extensions status|sync|update`は、引き続き個別機能拡張を検証・更新します。`build`だけが
214
+ メモリ上の`project.json`と埋め込みJavaScriptをbundle表現へ変換します。元のファイルを削除するモードは
215
+ ありません。
216
+
217
+ 安全に変換できない機能拡張は、動作を変えてbundleするのではなく拒否されます。現在の静的bundle契約では、
218
+ 次のすべてを満たす必要があります。
219
+
220
+ - すべてのメンバーがExtension Gallery形式の`Name`、`ID`、`Description`、`By`、`License`ヘッダーを持つ
221
+ - ヘッダーID、マニフェストID、ランタイム`getInfo().id`が同一である
222
+ - すべてのメンバーが`Scratch.extensions.register`をちょうど1回かつ同期的に呼び出すclassicスクリプトである
223
+ - XMLブロックを使用するメンバーがない
224
+ - ブロック、monitor、動的ブロックメタデータ以外に未分類のopcode参照が残らない
225
+
226
+ bundleは、通常のcommand、reporter、boolean、event、button、label、静的および動的メニュー、
227
+ カスタムフィールド、グローバルおよびターゲット機能拡張ストレージを名前空間化します。子機能拡張からの
228
+ `runtime.startHats`呼び出しもbundle済みopcodeへ変換します。メンバーが`runtime.getOpcodeFunction()`を
229
+ 呼び出した場合は、同じbundleに含まれるいずれかのメンバーIDで始まるopcodeをランタイムで変換します。
230
+ これにより、自身のopcode参照だけでなく、Asset ManagerメンバーがAnimated Textメンバーのhandlerを
231
+ 解決するようなmember間呼び出しにも対応します。
232
+
233
+ 変換するのは`getOpcodeFunction()`へ渡すopcodeだけです。VMが返す関数は変更せずそのまま返すため、関数の
234
+ 束縛、handlerの引数、同期的な戻り値、Promiseの戻り値は保持されます。先頭部分がbundle member IDではない
235
+ core、外部機能拡張、未知のopcodeは変更せずVMへ渡します。opcode文字列を受け取るほかのAPIは、個別に明記
236
+ されていない限り、この互換性契約の対象外です。
237
+
238
+ bundleは、マニフェストの`members`順と、各メンバーの`getInfo().blocks`内のブロック定義順を保持します。
239
+ TurboWarp Editorのパレットでは、各グループが次の形式の装飾済みLABEL見出しから始まります。
240
+
241
+ ```text
242
+ ◆ <name> [<memberId>] ◆
243
+ ```
244
+
245
+ メンバー名を先頭へ置くことで、幅の狭いTurboWarpパレットでも名前が見えるようにします。メンバーグループは、
246
+ 連続する2つの`---` separatorで区切られます。生成LABELには、次の機械可読メタデータも含まれます。
247
+
248
+ ```js
249
+ {
250
+ sb3Toolchain: {
251
+ kind: 'bundle-member-heading',
252
+ memberId,
253
+ },
254
+ }
255
+ ```
256
+
257
+ メンバーの`getInfo()`が空でない文字列[`docsURI`](https://docs.turbowarp.org/development/extensions/assorted-apis#docsuri)を返す場合、
258
+ bundleはそのメンバー見出しの直後に`Open Documentation`ボタンを挿入します。機能拡張コードへの委譲ではなく、TurboWarp標準の
259
+ `OPEN_EXTENSION_DOCS` callbackを使用するため、通常の`docsURI`と同じ動作を保持します。生成ボタンには別の
260
+ メタデータを付け、URIを安全にXML escapeします。
261
+
262
+ ```js
263
+ {
264
+ sb3Toolchain: {
265
+ docsURI,
266
+ kind: 'bundle-member-docs',
267
+ memberId,
268
+ },
269
+ }
270
+ ```
271
+
272
+ `docsURI`を持たないメンバーにはボタンを追加しません。メンバー自身が定義するXMLブロックは引き続き非対応で、
273
+ ツールが生成するXMLはこの限定されたドキュメントボタンだけです。
274
+
275
+ メンバーが元から定義しているLABELエントリとseparatorは、位置も含めて変更せず保持されます。そのため、
276
+ 装飾済みbundle見出しと幅の広い二重separatorは、元の見出しや通常のseparatorと視覚的に区別できます。
277
+ ツールは`sb3Toolchain`メタデータで生成見出しを識別し、その直前にある2つのseparatorをbundleグループ境界として
278
+ 扱えます。
279
+
280
+ 生成されるパレットの視覚的階層は次のようになります。
281
+
282
+ ```text
283
+ ┌─ Project Extension Bundle ─────────────────────────────┐
284
+ │ ◆ Alpha Tools [alpha] ◆ │ ← 生成見出し
285
+ │ Open Documentation │ ← 生成されたdocsURIボタン
286
+ │ alpha block 1 │
287
+ │ Alpha original heading │ ← 元のLABEL
288
+ │ │ ← 元のseparator
289
+ │ alpha block 2 │
290
+ │ │
291
+ │ │ ← 生成された二重separator
292
+ │ ◆ Beta Tools [beta] ◆ │ ← 生成見出し
293
+ │ beta block 1 │
294
+ └────────────────────────────────────────────────────────┘
295
+ ```
296
+
297
+ ## bundleの設定
298
+
299
+ まずdry runで、選択したメンバー、ヘッダーメタデータ、衝突、opcode参照を検証します。
300
+
301
+ ```bash
302
+ sb3-toolchain extensions bundle app \
303
+ --id projectbundle \
304
+ --name "Project Extension Bundle" \
305
+ extensionone extensiontwo
306
+ ```
307
+
308
+ メンバーIDを省略すると、まだ別のbundleに割り当てられていないすべての埋め込み機能拡張が選択されます。
309
+ bundleには少なくとも2つのメンバーが必要です。適用前に結果を確認してください。
310
+
311
+ ```bash
312
+ sb3-toolchain extensions bundle app \
313
+ --id projectbundle \
314
+ --name "Project Extension Bundle" \
315
+ extensionone extensiontwo \
316
+ --yes
317
+ sb3-toolchain check app
318
+ sb3-toolchain build app --output dist/project.sb3
319
+ ```
320
+
321
+ 生成SB3では、メンバーのopcodeが次のように変換されます。
322
+
323
+ ```text
324
+ 元の機能拡張のgetInfo() opcode: doSomething
325
+ bundleのgetInfo() opcode: extensionone__doSomething
326
+ 元のproject.json opcode: extensionone_doSomething
327
+ bundle済みproject.json opcode: projectbundle_extensionone__doSomething
328
+ ```
329
+
330
+ bundleは各元opcodeに`memberId + "__"`を加えるため、異なるメンバーの同一opcodeが衝突することはありません。
331
+ メンバーIDは`[a-z0-9]+`に制限されるため、区切りは明確です。同じメンバー内で変換後のopcodeが衝突する場合は、
332
+ bundleの読み込みを拒否します。
333
+
334
+ `extensions`と`extensionURLs`には`projectbundle`だけが現れ、生成JavaScriptは
335
+ `Scratch.extensions.register`を1回呼び出します。そのJavaScriptの先頭コメントには全メンバーの名前、ID、
336
+ 作者、説明、ライセンスが列挙され、ユーザーは権限を許可する前に確認できます。
337
+
338
+ JavaScriptの末尾には`SB3-Toolchain-Reversible-Bundle-v1`復元カプセルが含まれます。カプセルは各メンバーの
339
+ 元のdata URL、メンバー順、元の`extensions`と`extensionURLs`の順序を記録します。
340
+
341
+ ## 展開ソースからの復元
342
+
343
+ 利用可能な成果物に応じて復元経路を選択します。
344
+
345
+ ```mermaid
346
+ flowchart TD
347
+ Start{"何を利用できますか?"}
348
+ Source["展開ソースディレクトリ"]
349
+ SB3["bundle済みSB3のみ"]
350
+ SourceCommand["extensions unbundle SOURCE_DIR"]
351
+ ArchiveCommand["extensions unbundle INPUT.sb3<br/>--output OUTPUT.sb3"]
352
+ Rebuild["保持されたproject.source.jsonと<br/>メンバーJSから再ビルド"]
353
+ Recover["復元カプセルを検証して<br/>プロジェクト変換を逆変換"]
354
+ Restored["個別機能拡張を持つSB3"]
355
+
356
+ Start -->|"信頼できるソース"| Source
357
+ Start -->|"配布成果物"| SB3
358
+ Source --> SourceCommand --> Rebuild --> Restored
359
+ SB3 --> ArchiveCommand --> Recover --> Restored
360
+ ```
361
+
362
+ まずdry runでunbundle計画を確認し、次に`--yes`を渡してbundle設定を削除します。
363
+
364
+ ```bash
365
+ sb3-toolchain extensions unbundle app projectbundle
366
+ sb3-toolchain extensions unbundle app projectbundle --yes
367
+ sb3-toolchain check app
368
+ sb3-toolchain build app --output dist/project.sb3 --yes
369
+ ```
370
+
371
+ 元のJavaScriptとプロジェクト表現が保持されているため、次のビルドでは個別IDとdata URLを復元し、ブロック、
372
+ 動的ブロックメタデータ、monitorのopcodeを元の値で再生成します。この形式のunbundleでは、配布SB3の
373
+ リバースエンジニアリングを試みません。保存済み`project.source.json`と個別JavaScriptからプロジェクトを
374
+ 再生成するため、推測によるopcode逆変換で情報が失われることはありません。bundle設定中に
375
+ `extensions update`を実行していた場合は、更新後の個別JavaScriptを使用してプロジェクトを復元します。
376
+
377
+ 展開ソースを信頼できる情報源として扱ってください。生成したbundle済みSB3を、同じ信頼できるソースへ
378
+ 再importしないでください。新しいディレクトリへimportすると、配布用の複合機能拡張が1つの通常機能拡張として
379
+ 展開され、個別の来歴は復元できません。既存の信頼できるソースを誤って選択した場合でも、通常のGit差分保護と
380
+ 置換確認が適用されます。
381
+
382
+ ## bundle済みSB3の直接復元
383
+
384
+ 復元カプセルを含むbundle済みSB3は、展開ソースがなくてもunbundleできます。`--yes`を指定しない限り、
385
+ コマンドはdry runです。
386
+
387
+ ```bash
388
+ sb3-toolchain extensions unbundle \
389
+ dist/project.sb3 projectbundle \
390
+ --output dist/project.unbundled.sb3
391
+ sb3-toolchain extensions unbundle \
392
+ dist/project.sb3 projectbundle \
393
+ --output dist/project.unbundled.sb3 \
394
+ --yes
395
+ ```
396
+
397
+ 直接unbundleでは次のすべてを復元します。
398
+
399
+ - bundle opcodeを`memberId_originalOpcode`へ戻し、ブロックID、`next`、`parent`、`inputs`は変更しない
400
+ - 通常ブロック、動的ブロックメタデータ、monitorのopcode
401
+ - bundleストレージの`components`を、元のメンバーIDをキーとするストレージへ変換
402
+ - 個別メンバーのdata URLと、元の`extensions`および`extensionURLs`の順序
403
+ - アセットエントリとそのバイト内容
404
+
405
+ bundle後にTurboWarpでブロックを追加、削除、移動できます。追加されたブロックも、opcodeが
406
+ `bundleId_memberId__originalOpcode`形式なら復元できます。複数のbundleを含むSB3は、すべてのbundleが有効な
407
+ 復元カプセルを持ち、メンバー集合が重複していなければ、任意の順序で1つずつunbundleできます。
408
+
409
+ ### 直接unbundleできない条件
410
+
411
+ ```mermaid
412
+ flowchart TD
413
+ Input["bundle済みSB3"]
414
+ Capsule{"有効な復元カプセル?"}
415
+ Order{"機能拡張IDの集合と<br/>順序が一致?"}
416
+ Mapping{"すべてのbundle opcodeが<br/>ちょうど1つのメンバーに対応?"}
417
+ Storage{"ストレージが衝突のない<br/>可逆形式1?"}
418
+ Write["unbundle済みSB3を書き込む"]
419
+ Refuse["安全に拒否して<br/>出力を変更しない"]
420
+
421
+ Input --> Capsule
422
+ Capsule -->|"はい"| Order
423
+ Capsule -->|"いいえ"| Refuse
424
+ Order -->|"はい"| Mapping
425
+ Order -->|"いいえ"| Refuse
426
+ Mapping -->|"はい"| Storage
427
+ Mapping -->|"いいえ"| Refuse
428
+ Storage -->|"はい"| Write
429
+ Storage -->|"いいえ"| Refuse
430
+ ```
431
+
432
+ 次のいずれかの条件に該当する場合、ツールは推測せず、出力を変更せずに操作を拒否します。
433
+
434
+ - 対象data URLに`SB3-Toolchain-Reversible-Bundle-v1`カプセルがない。復元カプセル導入前、別のツール、
435
+ または手作業でbundleが生成された場合が該当する
436
+ - bundle data URLまたはカプセルが削除、破損、重複している、形式バージョンが未対応、またはbundle ID、
437
+ メンバーID、元のJavaScriptヘッダーIDが一致しない
438
+ - bundle後に`project.extensions`または`extensionURLs`内のID集合や順序が変わった。たとえば別の機能拡張を
439
+ 追加または削除すると、元のメンバーの正確な挿入位置を安全に推測できない
440
+ - `bundleId_`で始まるopcodeをメンバーの`memberId__`名前空間へ割り当てられない、または通常ブロック、
441
+ 動的ブロックメタデータ、monitor以外に未分類のbundle opcode参照が残っている
442
+ - bundleストレージが`{formatVersion: 1, components: {...}}`ではない、未知のメンバーまたは追加のbundleレベル
443
+ フィールドを含む、あるいは復元するメンバーIDをすでに使用するストレージと衝突する
444
+ - 有効な可逆bundle間でメンバーが重複している
445
+ - ZIPが空、`project.json`が欠落または無効、エントリ名が安全でない、あるいはエントリ順を安全に保持できない
446
+
447
+ 展開ソースを利用できる場合、これらの条件があっても、ソースを使用する`extensions unbundle SOURCE_DIR`
448
+ ワークフローでbundle設定を削除してプロジェクトを再ビルドできます。復元カプセルを持たない古い生成SB3は、
449
+ そのSB3だけから直接逆変換することはできません。
450
+
451
+ 直接unbundleではアセットのバイト列を保持しますが、ZIPを決定的に再圧縮します。入力ZIPメタデータ、
452
+ エントリタイムスタンプ、アーカイブコメントのバイト単位での同一性は保持しません。
453
+
454
+ ## 検証
455
+
456
+ 静的検証では、ブラウザAPI、カメラ、renderer、機能拡張間の暗黙的な依存関係に対する互換性を証明できません。
457
+ bundle前後に同じプロジェクトレベルの自動テストを実行し、生成SB3を新しいTurboWarpセッションで開いて、
458
+ 次のすべてを確認してください。
459
+
460
+ - unsandboxed実行の確認が1回だけ表示される
461
+ - green flagの動作と、block、reporter、hat、monitor、menuの結果が変わらない
462
+ - カメラ、ネットワーク、ファイル選択、rendererアクセスなど、プロジェクトが使用する権限経路が動作する
463
+ - TurboWarpで再保存したSB3が機能拡張ストレージを保持し、再読み込み後も動作する
464
+
465
+ 互換性を検証できないメンバーは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、成果物、来歴をまとめて元に戻します。