@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.
- package/README.ja.md +151 -0
- package/README.md +9 -6
- package/docs/extension-bundles.md +45 -6
- package/docs/extension-id-migration.md +2 -0
- package/docs/ja/extension-bundles.md +465 -0
- package/docs/ja/extension-id-migration.md +69 -0
- package/docs/ja/source-format-v1.md +205 -0
- package/docs/ja/workflows.md +265 -0
- package/docs/source-format-v1.md +28 -9
- package/docs/workflows.md +33 -13
- package/package.json +4 -3
- package/src/build.js +8 -2
- package/src/cli.js +31 -4
- package/src/constants.js +1 -1
- package/src/extension-bundle.js +32 -1
- package/src/extension-dependencies.js +32 -19
- package/src/extension-sync.js +109 -20
- package/src/index.js +1 -0
- package/src/npm-extension-source.js +111 -0
- package/src/source.js +16 -2
- package/src/turbowarp-clean-up.js +295 -0
|
@@ -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、成果物、来歴をまとめて元に戻します。
|