@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 +147 -0
- package/README.md +3 -4
- package/docs/extension-bundles.md +27 -5
- package/docs/extension-id-migration.md +2 -0
- package/docs/ja/extension-bundles.md +449 -0
- package/docs/ja/extension-id-migration.md +69 -0
- package/docs/ja/source-format-v1.md +190 -0
- package/docs/ja/workflows.md +249 -0
- package/docs/source-format-v1.md +2 -0
- package/docs/workflows.md +2 -0
- package/package.json +4 -3
- package/src/constants.js +1 -1
- package/src/extension-bundle.js +21 -1
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.
|
|
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
|
-
◆
|
|
232
|
+
◆ <name> [<memberId>] ◆
|
|
231
233
|
```
|
|
232
234
|
|
|
233
|
-
|
|
234
|
-
machine-readable
|
|
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
|
-
│ ◆
|
|
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
|
-
│ ◆
|
|
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履歴を破壊しないでください。原因と影響範囲を調査可能な状態に保ちます。
|
package/docs/source-format-v1.md
CHANGED
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
|
+
"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
package/src/extension-bundle.js
CHANGED
|
@@ -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
|
+
'<': '<',
|
|
210
|
+
'>': '>',
|
|
211
|
+
'&': '&',
|
|
212
|
+
"'": ''',
|
|
213
|
+
'"': '"',
|
|
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: '◆
|
|
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);
|