@kubohiroya/sb3-toolchain 0.4.0 → 0.6.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 +9 -3
- package/README.md +10 -3
- package/docs/extension-bundles.md +18 -1
- package/docs/ja/extension-bundles.md +17 -1
- package/docs/ja/project-asset-additions.md +200 -0
- package/docs/ja/source-format-v1.md +25 -10
- package/docs/ja/workflows.md +34 -18
- package/docs/project-asset-additions.md +165 -0
- package/docs/source-format-v1.md +26 -9
- package/docs/workflows.md +31 -13
- package/package.json +4 -2
- package/src/build.js +25 -2
- package/src/cli.js +115 -10
- package/src/constants.js +1 -1
- package/src/extension-bundle.js +11 -0
- package/src/extension-dependencies.js +32 -19
- package/src/extension-sync.js +109 -20
- package/src/index.js +5 -0
- package/src/npm-extension-source.js +111 -0
- package/src/project-asset-additions.js +560 -0
- package/src/source.js +49 -8
- package/src/turbowarp-clean-up.js +295 -0
package/README.ja.md
CHANGED
|
@@ -9,11 +9,14 @@ Scratch 3およびTurboWarpの`.sb3`プロジェクトを、Gitで差分を確
|
|
|
9
9
|
|
|
10
10
|
- SB3を、整形済みの`project.source.json`、アセット、埋め込み機能拡張へ安全に展開
|
|
11
11
|
- アセット参照、MD5ハッシュ、ZIPエントリ、埋め込み機能拡張の対応関係を検証
|
|
12
|
-
- GitHub
|
|
12
|
+
- GitHubの固定コミットまたはインストール済みnpmパッケージの完全固定バージョンから埋め込み機能拡張を管理し、
|
|
13
|
+
SHA-256ハッシュをオフラインで検証
|
|
13
14
|
- 埋め込みJavaScriptを置き換える前に、バージョン付き機能拡張APIマニフェストを任意で比較
|
|
14
15
|
- 元のJavaScriptを削除せず、複数の機能拡張を1つの権限単位へ静的にbundleし、展開ソースまたは
|
|
15
16
|
bundle済みSB3から復元
|
|
16
17
|
- ZIPエントリ順、タイムスタンプ、圧縮設定を固定した決定的ビルド
|
|
18
|
+
- 展開済みbase sourceを変更せず、JSON/YAML build manifestからsprite、backdrop、costume、soundを追加
|
|
19
|
+
- 全ターゲットのスクリプトをTurboWarp風の決定的な「きれいにする」配置へ任意で整理
|
|
17
20
|
- import時に未コミットのGit変更を保護
|
|
18
21
|
- トランザクションによる置換とロールバックで既存出力を保護
|
|
19
22
|
- CLIとJavaScript APIの両方を提供
|
|
@@ -28,7 +31,7 @@ Scratch 3およびTurboWarpの`.sb3`プロジェクトを、Gitで差分を確
|
|
|
28
31
|
再現可能なインストールのため、検証済みのnpmバージョンを固定します。
|
|
29
32
|
|
|
30
33
|
```bash
|
|
31
|
-
pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.
|
|
34
|
+
pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.6.0
|
|
32
35
|
```
|
|
33
36
|
|
|
34
37
|
## クイックスタート
|
|
@@ -75,9 +78,11 @@ await validateSb3Source('app');
|
|
|
75
78
|
await buildSb3({
|
|
76
79
|
sourceDirectory: 'app',
|
|
77
80
|
outputPath: 'dist/project.sb3',
|
|
81
|
+
// 生成SB3だけを整理済みブロック座標にする場合に明示的に有効化します。
|
|
82
|
+
cleanUpBlocks: true,
|
|
78
83
|
});
|
|
79
84
|
|
|
80
|
-
const {archive} = await createDeterministicSb3('app');
|
|
85
|
+
const {archive} = await createDeterministicSb3('app', {cleanUpBlocks: true});
|
|
81
86
|
|
|
82
87
|
const integrity = extensionIntegrity(await readFile('app/extensions/example.js'));
|
|
83
88
|
|
|
@@ -128,6 +133,7 @@ await unbundleSb3({
|
|
|
128
133
|
|
|
129
134
|
- [`docs/ja/workflows.md`](docs/ja/workflows.md): SB3ソースと機能拡張を管理するワークフロー
|
|
130
135
|
- [`docs/ja/source-format-v1.md`](docs/ja/source-format-v1.md): 展開ソース形式と決定的出力
|
|
136
|
+
- [`docs/ja/project-asset-additions.md`](docs/ja/project-asset-additions.md): `--project-assets`のJSON/YAML、backdrop、編集/strict lock仕様
|
|
131
137
|
- [`docs/ja/extension-id-migration.md`](docs/ja/extension-id-migration.md): プロジェクトで使用中の機能拡張IDの移行
|
|
132
138
|
- [`docs/ja/extension-api-compatibility.md`](docs/ja/extension-api-compatibility.md): 機能拡張更新時の任意の静的API互換性検査
|
|
133
139
|
- [`docs/ja/extension-bundles.md`](docs/ja/extension-bundles.md): 1つの権限単位への静的bundleと可逆的なunbundle
|
package/README.md
CHANGED
|
@@ -9,11 +9,15 @@ expanded sources and rebuilding bit-for-bit identical SB3 files from the same in
|
|
|
9
9
|
|
|
10
10
|
- Safely expand an SB3 into formatted `project.source.json`, assets, and embedded extensions
|
|
11
11
|
- Validate asset references, MD5 hashes, ZIP entries, and embedded extension mappings
|
|
12
|
-
-
|
|
12
|
+
- Manage embedded extensions from pinned GitHub commits or exact installed npm package versions and
|
|
13
|
+
verify their SHA-256 hashes offline
|
|
13
14
|
- Optionally compare versioned extension API manifests before replacing embedded JavaScript
|
|
14
15
|
- Statically bundle multiple extensions into one permission unit without deleting their original
|
|
15
16
|
JavaScript, then restore them from either the expanded source or the bundled SB3
|
|
16
17
|
- Produce deterministic builds with fixed ZIP entry order, timestamps, and compression settings
|
|
18
|
+
- Add sprites, backdrops, costumes, and sounds from an optional JSON or YAML build manifest without
|
|
19
|
+
modifying the expanded base source
|
|
20
|
+
- Optionally lay out every target's scripts in a deterministic TurboWarp-style cleaned arrangement
|
|
17
21
|
- Protect uncommitted Git changes when importing
|
|
18
22
|
- Protect existing output through transactional replacement and rollback
|
|
19
23
|
- Provide both a CLI and a JavaScript API
|
|
@@ -28,7 +32,7 @@ expanded sources and rebuilding bit-for-bit identical SB3 files from the same in
|
|
|
28
32
|
Pin the verified npm version for reproducible installation.
|
|
29
33
|
|
|
30
34
|
```bash
|
|
31
|
-
pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.
|
|
35
|
+
pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.6.0
|
|
32
36
|
```
|
|
33
37
|
|
|
34
38
|
## Quick start
|
|
@@ -75,9 +79,11 @@ await validateSb3Source('app');
|
|
|
75
79
|
await buildSb3({
|
|
76
80
|
sourceDirectory: 'app',
|
|
77
81
|
outputPath: 'dist/project.sb3',
|
|
82
|
+
// Opt in to cleaned block coordinates in the generated SB3 only:
|
|
83
|
+
cleanUpBlocks: true,
|
|
78
84
|
});
|
|
79
85
|
|
|
80
|
-
const {archive} = await createDeterministicSb3('app');
|
|
86
|
+
const {archive} = await createDeterministicSb3('app', {cleanUpBlocks: true});
|
|
81
87
|
|
|
82
88
|
const integrity = extensionIntegrity(await readFile('app/extensions/example.js'));
|
|
83
89
|
|
|
@@ -128,6 +134,7 @@ await unbundleSb3({
|
|
|
128
134
|
|
|
129
135
|
- [`docs/workflows.md`](docs/workflows.md): SB3 source and extension management workflows
|
|
130
136
|
- [`docs/source-format-v1.md`](docs/source-format-v1.md): expanded source format and deterministic output
|
|
137
|
+
- [`docs/project-asset-additions.md`](docs/project-asset-additions.md): JSON/YAML `--project-assets`, backdrops, and editable or strict locks
|
|
131
138
|
- [`docs/extension-id-migration.md`](docs/extension-id-migration.md): migration of extension IDs already used by a project
|
|
132
139
|
- [`docs/extension-api-compatibility.md`](docs/extension-api-compatibility.md) ([日本語](docs/ja/extension-api-compatibility.md)): opt-in static API compatibility checks for extension updates
|
|
133
140
|
- [`docs/extension-bundles.md`](docs/extension-bundles.md): static bundling into one permission unit and reversible unbundling
|
|
@@ -180,6 +180,13 @@ sequenceDiagram
|
|
|
180
180
|
|
|
181
181
|
A->>W: startHats("alpha_whenReady")
|
|
182
182
|
W->>VM: startHats("projectbundle_alpha__whenReady")
|
|
183
|
+
|
|
184
|
+
A->>W: getOpcodeFunction("beta_echo")
|
|
185
|
+
W->>VM: getOpcodeFunction("projectbundle_beta__echo")
|
|
186
|
+
VM-->>A: Bundled opcode handler
|
|
187
|
+
A->>C: Call handler(args, util)
|
|
188
|
+
C->>B: Call original echo(args, util)
|
|
189
|
+
B-->>A: Result or Promise
|
|
183
190
|
```
|
|
184
191
|
|
|
185
192
|
### Data transformations
|
|
@@ -192,6 +199,7 @@ sequenceDiagram
|
|
|
192
199
|
| Stored project opcode | `alpha_doSomething` | `projectbundle_alpha__doSomething` |
|
|
193
200
|
| Menu and custom-field names | Member-local names | `memberId__` namespace |
|
|
194
201
|
| `startHats()` opcode | `alpha_whenReady` | `projectbundle_alpha__whenReady` |
|
|
202
|
+
| `getOpcodeFunction()` | `beta_echo` | `projectbundle_beta__echo` |
|
|
195
203
|
| Extension storage | `storage.alpha`, `storage.beta` | `storage.projectbundle.components.alpha/beta` |
|
|
196
204
|
| Block IDs and graph links | Original IDs and `next`/`parent`/`inputs` | Unchanged |
|
|
197
205
|
|
|
@@ -222,7 +230,16 @@ behavior. The current static-bundle contract requires all of the following:
|
|
|
222
230
|
|
|
223
231
|
The bundle namespaces ordinary commands, reporters, booleans, events, buttons, labels, static and
|
|
224
232
|
dynamic menus, custom fields, and global and target extension storage. Calls from child extensions
|
|
225
|
-
to `runtime.startHats` are also translated to bundled opcodes.
|
|
233
|
+
to `runtime.startHats` are also translated to bundled opcodes. When a member calls
|
|
234
|
+
`runtime.getOpcodeFunction()`, an opcode beginning with any member ID in the same bundle is
|
|
235
|
+
translated at runtime. This supports both self references and calls to another member, such as an
|
|
236
|
+
Asset Manager member resolving an Animated Text member's handler.
|
|
237
|
+
|
|
238
|
+
Only the opcode passed to `getOpcodeFunction()` is adapted. The function returned by the VM is
|
|
239
|
+
passed through unchanged, so its binding, handler arguments, synchronous result, or Promise result
|
|
240
|
+
are preserved. Core, external-extension, and unknown opcodes whose prefix is not a bundle member ID
|
|
241
|
+
are passed to the VM unchanged. Other APIs that carry opcode strings are outside this compatibility
|
|
242
|
+
contract unless documented separately.
|
|
226
243
|
|
|
227
244
|
The bundle preserves the `members` order from the manifest and the block-definition order within
|
|
228
245
|
each member's `getInfo().blocks`. In the TurboWarp Editor palette, each group begins with a decorated
|
|
@@ -176,6 +176,13 @@ sequenceDiagram
|
|
|
176
176
|
|
|
177
177
|
A->>W: startHats("alpha_whenReady")
|
|
178
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
|
|
179
186
|
```
|
|
180
187
|
|
|
181
188
|
### データ変換
|
|
@@ -188,6 +195,7 @@ sequenceDiagram
|
|
|
188
195
|
| 保存されるプロジェクトopcode | `alpha_doSomething` | `projectbundle_alpha__doSomething` |
|
|
189
196
|
| メニューとカスタムフィールド名 | メンバー内の名前 | `memberId__`名前空間 |
|
|
190
197
|
| `startHats()`のopcode | `alpha_whenReady` | `projectbundle_alpha__whenReady` |
|
|
198
|
+
| `getOpcodeFunction()` | `beta_echo` | `projectbundle_beta__echo` |
|
|
191
199
|
| 機能拡張ストレージ | `storage.alpha`、`storage.beta` | `storage.projectbundle.components.alpha/beta` |
|
|
192
200
|
| ブロックIDとグラフリンク | 元のIDと`next`/`parent`/`inputs` | 変更なし |
|
|
193
201
|
|
|
@@ -217,7 +225,15 @@ bundle設定は`embedded-extensions.json`だけに追加されます。信頼で
|
|
|
217
225
|
|
|
218
226
|
bundleは、通常のcommand、reporter、boolean、event、button、label、静的および動的メニュー、
|
|
219
227
|
カスタムフィールド、グローバルおよびターゲット機能拡張ストレージを名前空間化します。子機能拡張からの
|
|
220
|
-
`runtime.startHats`呼び出しもbundle済みopcode
|
|
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
|
+
されていない限り、この互換性契約の対象外です。
|
|
221
237
|
|
|
222
238
|
bundleは、マニフェストの`members`順と、各メンバーの`getInfo().blocks`内のブロック定義順を保持します。
|
|
223
239
|
TurboWarp Editorのパレットでは、各グループが次の形式の装飾済みLABEL見出しから始まります。
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# `--project-assets`: project asset追加build入力
|
|
2
|
+
|
|
3
|
+
`--project-assets`は、展開済みSB3 sourceを編集せず、生成するSB3にStage backdrop、sprite costume、
|
|
4
|
+
stage/sprite sound、新規spriteを追加するためのbuild入力です。JSONとYAMLを使用できます。
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
sb3-toolchain check app \
|
|
8
|
+
--project-assets stories/my-story/project-assets.yml \
|
|
9
|
+
--allow-asset-root resources
|
|
10
|
+
|
|
11
|
+
sb3-toolchain build app \
|
|
12
|
+
--project-assets stories/my-story/project-assets.yml \
|
|
13
|
+
--allow-asset-root resources \
|
|
14
|
+
--output dist/my-story.sb3
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
`check`はSB3を書き出さず、base sourceとproject assetsをメモリ上で合成して検証します。`build`だけが
|
|
18
|
+
出力SB3を生成します。どちらもbase sourceの`project.source.json`、`sb3-source.json`、`assets/`を
|
|
19
|
+
変更しません。
|
|
20
|
+
|
|
21
|
+
## YAML形式(推奨)
|
|
22
|
+
|
|
23
|
+
`.yml`または`.yaml`は、DSL 4.0の`assets:`と同様に、asset IDをmapping key、`kind`をasset種別として
|
|
24
|
+
記述します。新規spriteの表示属性だけを`sprites:`へ分離します。
|
|
25
|
+
|
|
26
|
+
```yaml
|
|
27
|
+
formatVersion: 1
|
|
28
|
+
|
|
29
|
+
sprites:
|
|
30
|
+
Princess:
|
|
31
|
+
layerOrder: 6
|
|
32
|
+
visible: false
|
|
33
|
+
x: 4
|
|
34
|
+
y: -16
|
|
35
|
+
size: 70
|
|
36
|
+
direction: 90
|
|
37
|
+
draggable: false
|
|
38
|
+
rotationStyle: all around
|
|
39
|
+
volume: 100
|
|
40
|
+
|
|
41
|
+
assets:
|
|
42
|
+
Princess:
|
|
43
|
+
kind: costume
|
|
44
|
+
target: Princess
|
|
45
|
+
file: ../../resources/Princess.png
|
|
46
|
+
bitmapResolution: 2
|
|
47
|
+
rotationCenterX: 507
|
|
48
|
+
rotationCenterY: 507
|
|
49
|
+
license: 'CC-BY-SA-4.0: ../../LICENSES.md'
|
|
50
|
+
|
|
51
|
+
DragonCastle:
|
|
52
|
+
kind: backdrop
|
|
53
|
+
file: ../../resources/DragonCastle.svg
|
|
54
|
+
rotationCenterX: 240
|
|
55
|
+
rotationCenterY: 180
|
|
56
|
+
|
|
57
|
+
OpeningSound:
|
|
58
|
+
kind: sound
|
|
59
|
+
file: ../../resources/OpeningSound.mp3
|
|
60
|
+
|
|
61
|
+
PrincessVoice:
|
|
62
|
+
kind: sound
|
|
63
|
+
target: Princess
|
|
64
|
+
file: ../../resources/PrincessVoice.wav
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
- `backdrop`は常にStageの`costumes`へ追加します。`target`は指定しません。
|
|
68
|
+
- `costume`は`target`で指定したspriteの`costumes`へ追加します。
|
|
69
|
+
- `sound`は`target`省略時にStage、指定時にそのspriteの`sounds`へ追加します。
|
|
70
|
+
- 既存spriteへ追加する場合、そのspriteを`sprites:`へ重ねて宣言する必要はありません。
|
|
71
|
+
- 新規spriteは`sprites:`で宣言し、`assets:`から1件以上のcostumeを割り当てます。
|
|
72
|
+
- asset ID(例: `Princess`)がScratch内のcostume/backdrop/sound名になります。別名にする場合だけ
|
|
73
|
+
`name`を指定します。
|
|
74
|
+
|
|
75
|
+
YAMLは1.2として解釈します。duplicate key、複数document、anchor、alias、merge key、custom tag、
|
|
76
|
+
`__proto__`/`constructor`/`prototype` keyを拒否します。YAMLコメントは使用できます。
|
|
77
|
+
|
|
78
|
+
## JSON形式
|
|
79
|
+
|
|
80
|
+
`.json`はYAMLと同じfield構成です。次は上のPrincess部分と等価です。
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
{
|
|
84
|
+
"formatVersion": 1,
|
|
85
|
+
"sprites": {
|
|
86
|
+
"Princess": {
|
|
87
|
+
"layerOrder": 6,
|
|
88
|
+
"visible": false,
|
|
89
|
+
"x": 4,
|
|
90
|
+
"y": -16,
|
|
91
|
+
"size": 70,
|
|
92
|
+
"direction": 90,
|
|
93
|
+
"draggable": false,
|
|
94
|
+
"rotationStyle": "all around",
|
|
95
|
+
"volume": 100
|
|
96
|
+
}
|
|
97
|
+
},
|
|
98
|
+
"assets": {
|
|
99
|
+
"Princess": {
|
|
100
|
+
"kind": "costume",
|
|
101
|
+
"target": "Princess",
|
|
102
|
+
"file": "../../resources/Princess.png",
|
|
103
|
+
"bitmapResolution": 2,
|
|
104
|
+
"rotationCenterX": 507,
|
|
105
|
+
"rotationCenterY": 507
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
JSONでもduplicate keyを拒否します。`.json`、`.yml`、`.yaml`以外の拡張子は受け付けません。
|
|
112
|
+
|
|
113
|
+
## 編集用の通常モード
|
|
114
|
+
|
|
115
|
+
画像を描き直したり、音声を録り直したりしながら同じファイルへ上書きする場合、`size`と`sha256`は
|
|
116
|
+
記述しません。`file`の現在のbyte列を正本として、buildごとにScratch用MD5 `assetId`を再計算します。
|
|
117
|
+
|
|
118
|
+
画像では次を指定します。
|
|
119
|
+
|
|
120
|
+
| field | 必須 | 内容 |
|
|
121
|
+
| ------------------------------------ | --------------- | --------------------------------- |
|
|
122
|
+
| `kind` | 必須 | `backdrop`または`costume` |
|
|
123
|
+
| `target` | costumeだけ必須 | 追加先sprite名 |
|
|
124
|
+
| `file` | 必須 | manifestからの相対path |
|
|
125
|
+
| `rotationCenterX`, `rotationCenterY` | 必須 | Scratchの回転中心 |
|
|
126
|
+
| `bitmapResolution` | 任意 | `1`(既定)または`2` |
|
|
127
|
+
| `name` | 任意 | Scratch内の名前。省略時はasset ID |
|
|
128
|
+
|
|
129
|
+
音声では通常、`kind: sound`と`file`だけで足ります。open-sourceの`music-metadata`を使ってMP3/WAVを
|
|
130
|
+
解析し、`rate`と`sampleCount`を自動取得します。sprite soundだけは`target`も指定します。`dataFormat`は画像・音声ともfile拡張子から
|
|
131
|
+
取得します。
|
|
132
|
+
|
|
133
|
+
## 配布用のstrict lock
|
|
134
|
+
|
|
135
|
+
再現対象の入力byte列を固定する場合だけ、次のfieldを追加します。fieldごとに独立して検証するため、
|
|
136
|
+
必要なものだけ指定できます。
|
|
137
|
+
|
|
138
|
+
```yaml
|
|
139
|
+
assets:
|
|
140
|
+
Princess:
|
|
141
|
+
kind: costume
|
|
142
|
+
target: Princess
|
|
143
|
+
file: ../../resources/Princess.png
|
|
144
|
+
rotationCenterX: 507
|
|
145
|
+
rotationCenterY: 507
|
|
146
|
+
size: 220534
|
|
147
|
+
sha256: e9d1857528a619e4a56ebd232fea4767fd6bdd00b20ac67a90c859c6b3598e83
|
|
148
|
+
dataFormat: png
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
| strict field | 検証内容 |
|
|
152
|
+
| --------------------- | -------------------------------------- |
|
|
153
|
+
| `size` | fileのbyte数と一致すること |
|
|
154
|
+
| `sha256` | fileのSHA-256と一致すること |
|
|
155
|
+
| `dataFormat` | file拡張子から得たformatと一致すること |
|
|
156
|
+
| `rate`, `sampleCount` | 音声から自動取得した値と一致すること |
|
|
157
|
+
|
|
158
|
+
指定していないstrict fieldは不一致判定に使用しません。`license`は任意の1行の出典・ライセンス情報として
|
|
159
|
+
検証しますが、Scratchの`project.json`にはコピーしません。
|
|
160
|
+
|
|
161
|
+
同じbase source、manifest、asset byte列、toolchain versionからはbit-for-bit同一のSB3を生成します。
|
|
162
|
+
通常モードでasset fileを上書きすれば、次のbuild結果が変わるのは意図した動作です。配布時に意図しない
|
|
163
|
+
上書きを検出する必要があれば`size`と`sha256`を指定します。
|
|
164
|
+
|
|
165
|
+
## pathと入力の安全性
|
|
166
|
+
|
|
167
|
+
asset fileは既定でmanifest directory内に限定します。共有素材directoryを参照する場合だけ、
|
|
168
|
+
repeatableな`--allow-asset-root`で明示的に許可します。
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
sb3-toolchain build app \
|
|
172
|
+
--project-assets stories/my-story/project-assets.yml \
|
|
173
|
+
--allow-asset-root resources/images \
|
|
174
|
+
--allow-asset-root resources/sounds \
|
|
175
|
+
--output dist/my-story.sb3
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
絶対path、許可rootからの逸脱、symlink経由、通常file以外、拡張子と指定`dataFormat`の不一致、既存の
|
|
179
|
+
target/costume/backdrop/sound名との衝突はfail-closedで拒否します。manifest自体は1 MiB以下の
|
|
180
|
+
通常fileである必要があります。
|
|
181
|
+
|
|
182
|
+
## JavaScript API
|
|
183
|
+
|
|
184
|
+
CLIと同じ入力を`createDeterministicSb3`または`buildSb3`へ渡せます。
|
|
185
|
+
|
|
186
|
+
```js
|
|
187
|
+
await createDeterministicSb3('app', {
|
|
188
|
+
projectAssetsPath: 'stories/my-story/project-assets.yml',
|
|
189
|
+
allowedAssetRoots: ['resources'],
|
|
190
|
+
});
|
|
191
|
+
|
|
192
|
+
await buildSb3({
|
|
193
|
+
sourceDirectory: 'app',
|
|
194
|
+
projectAssetsPath: 'stories/my-story/project-assets.yml',
|
|
195
|
+
allowedAssetRoots: ['resources'],
|
|
196
|
+
outputPath: 'dist/my-story.sb3',
|
|
197
|
+
});
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
`projectAssetsPath`を指定しなければ、project assetを追加しない従来のbuildへ戻ります。
|
|
@@ -42,8 +42,8 @@ embedded-extension:extensions/<extensionId>.js
|
|
|
42
42
|
|
|
43
43
|
## `embedded-extensions.json`
|
|
44
44
|
|
|
45
|
-
このファイルは、埋め込み機能拡張のdata URL情報と展開先パスを記録します。GitHub
|
|
46
|
-
|
|
45
|
+
このファイルは、埋め込み機能拡張のdata URL情報と展開先パスを記録します。GitHubまたはインストール済み
|
|
46
|
+
npmパッケージから管理する機能拡張には、任意の`source`メタデータを追加できます。
|
|
47
47
|
|
|
48
48
|
```json
|
|
49
49
|
{
|
|
@@ -74,10 +74,25 @@ embedded-extension:extensions/<extensionId>.js
|
|
|
74
74
|
}
|
|
75
75
|
```
|
|
76
76
|
|
|
77
|
+
完全固定したnpm依存では、GitHub固有のフィールドをパッケージ情報へ置き換えます。
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"provider": "npm",
|
|
82
|
+
"package": "@owner/example-extension",
|
|
83
|
+
"version": "1.2.3",
|
|
84
|
+
"artifact": "dist/example.js",
|
|
85
|
+
"integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- `provider`: `github`または`npm`
|
|
77
90
|
- `repository`: `<owner>/<repository>`形式のGitHubリポジトリ
|
|
78
91
|
- `ref`: 更新候補として追跡するブランチ、タグ、またはコミット
|
|
79
92
|
- `resolvedCommit`: 現在のファイルの取得に使用した、小文字40文字のコミットSHA
|
|
80
|
-
- `
|
|
93
|
+
- `package`: スコープを含む完全なnpmパッケージ名
|
|
94
|
+
- `version`: インストール済み`package.json`に記録された完全固定のsemantic version。範囲指定は不可
|
|
95
|
+
- `artifact`: リポジトリまたはnpmパッケージのルートを基準にしたJavaScript成果物のパス
|
|
81
96
|
- `integrity`: 現在のファイルのSRI形式SHA-256
|
|
82
97
|
- `apiManifest`: 任意で使用するAPI互換性メタデータ
|
|
83
98
|
- `artifact`: 同じGitHubリポジトリを基準にしたAPIマニフェストのパス
|
|
@@ -89,19 +104,19 @@ embedded-extension:extensions/<extensionId>.js
|
|
|
89
104
|
|
|
90
105
|
- 実ファイルのSHA-256が`integrity`と一致する
|
|
91
106
|
- ファイルの`// ID: <extensionId>`ヘッダーが`id`と一致する
|
|
92
|
-
- リポジトリ、ref
|
|
107
|
+
- GitHubリポジトリ、ref、コミット、npmパッケージ、完全固定バージョン、成果物パスが安全な形式である
|
|
93
108
|
- `apiManifest`が存在する場合、そのJSONスキーマ、ID、形式バージョン、パス、SHA-256が有効である
|
|
94
109
|
|
|
95
110
|
既存の展開ソースディレクトリへSB3を再importすると、同じIDとパスの`source`メタデータが保持されます。
|
|
96
111
|
importしたファイルが記録済みのハッシュまたはIDと一致しない場合、既存の出力を変更せずにimportを拒否します。
|
|
97
112
|
新規importでは来歴を推測できないため、`source`は自動作成されません。
|
|
98
113
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
114
|
+
GitHub sourceの`extensions sync`は変更不能な`resolvedCommit`からJavaScriptと任意のAPIマニフェストを
|
|
115
|
+
ダウンロードします。npm sourceでは、最寄りの親`node_modules`にインストールされた完全固定パッケージから、
|
|
116
|
+
ネットワークを使わずに読み込みます。どちらもIDとハッシュが既存メタデータに一致する場合だけ復元します。
|
|
117
|
+
パッケージマネージャーで新しい完全固定npmバージョンを導入した後に`extensions update`を実行すると、成果物を
|
|
118
|
+
コピーして`version`とintegrityを更新します。GitHub更新では`ref`を解決して`resolvedCommit`を更新します。
|
|
119
|
+
どちらも候補APIマニフェストを事前に比較し、選択した全項目の検証が終わるまで展開ソースを変更しません。
|
|
105
120
|
|
|
106
121
|
機能拡張IDの移行では、マニフェストの`id`と`path`、`project.source.json`内の既知の参照、
|
|
107
122
|
`extensions/<id>.js`を1回のトランザクションで変更します。`extensions update`の一部として管理対象機能拡張を
|
package/docs/ja/workflows.md
CHANGED
|
@@ -84,25 +84,37 @@ sb3-toolchain build app --output dist/project.sb3
|
|
|
84
84
|
バイト単位で同一のSB3が生成されます。既存出力が同一なら変更しません。異なる場合は、置換の確認または
|
|
85
85
|
`--yes`が必要です。
|
|
86
86
|
|
|
87
|
+
生成SB3へ書き込む前に、全ターゲットのトップレベルスクリプトを整理するには、明示的にオプションを指定します。
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
sb3-toolchain build app --output dist/project.sb3 --clean-up-blocks
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`--clean-up-blocks`は、TurboWarpの「きれいにする」配置と同じ開始座標、列の判定範囲、余白を使用します。
|
|
94
|
+
ブロック、変数、リスト、コメントは削除せず、ブロックに付いたコメントはスクリプトと一緒に移動します。変換する
|
|
95
|
+
のは生成物内の`project.json`だけであり、展開ソースは変更しません。生成SB3をTurboWarpで開いた後は座標変更を
|
|
96
|
+
元に戻せない場合があります。ソース座標へ戻すにはこのオプションを外して再ビルドしてください。
|
|
97
|
+
|
|
87
98
|
プロジェクト固有のテストに加えて、生成SB3をTurboWarpで開き、起動、主要な操作、画像、音声、埋め込み
|
|
88
99
|
機能拡張の動作を確認してください。
|
|
89
100
|
|
|
90
101
|
## 管理対象の埋め込み機能拡張
|
|
91
102
|
|
|
92
|
-
`embedded-extensions.json`の`source`オブジェクトには、GitHub
|
|
93
|
-
|
|
94
|
-
|
|
103
|
+
`embedded-extensions.json`の`source`オブジェクトには、GitHubコミットの来歴またはインストール済みnpm
|
|
104
|
+
パッケージの完全固定バージョンと、成果物パス、SHA-256を記録できます。更新時の静的互換性検査に使用する
|
|
105
|
+
バージョン付きAPIマニフェストも任意で設定できます。完全なスキーマは
|
|
106
|
+
[`source-format-v1.md`](source-format-v1.md)を参照してください。
|
|
95
107
|
|
|
96
108
|
機能拡張コマンドの役割は次のとおりです。
|
|
97
109
|
|
|
98
|
-
| コマンド | ネットワーク | refの解決
|
|
99
|
-
| ----------------------- | ------------ |
|
|
100
|
-
| `extensions status` |
|
|
101
|
-
| `extensions sync` |
|
|
102
|
-
| `extensions update` |
|
|
103
|
-
| `extensions migrate-id` | なし | なし
|
|
104
|
-
| `extensions bundle` | なし | なし
|
|
105
|
-
| `extensions unbundle` | なし | なし
|
|
110
|
+
| コマンド | ネットワーク | refの解決 | メタデータ更新 | 目的 |
|
|
111
|
+
| ----------------------- | ------------ | ---------- | -------------- | -------------------------------------- |
|
|
112
|
+
| `extensions status` | GitHubのみ | GitHubのみ | なし | 上流または導入済みパッケージを確認 |
|
|
113
|
+
| `extensions sync` | GitHubのみ | なし | なし | 宣言したsourceからファイルを復元 |
|
|
114
|
+
| `extensions update` | GitHubのみ | GitHubのみ | あり | 上流または導入済みパッケージを採用 |
|
|
115
|
+
| `extensions migrate-id` | なし | なし | ID/参照 | プロジェクトで使用中の機能拡張IDを移行 |
|
|
116
|
+
| `extensions bundle` | なし | なし | bundle設定 | 機能拡張を1つの権限単位へ統合 |
|
|
117
|
+
| `extensions unbundle` | なし | なし | 設定またはSB3 | 個別機能拡張を使用する出力へ復元 |
|
|
106
118
|
|
|
107
119
|
### 更新の確認
|
|
108
120
|
|
|
@@ -110,8 +122,8 @@ sb3-toolchain build app --output dist/project.sb3
|
|
|
110
122
|
sb3-toolchain extensions status app
|
|
111
123
|
```
|
|
112
124
|
|
|
113
|
-
`status
|
|
114
|
-
|
|
125
|
+
`status`はローカルファイルを変更しません。GitHub sourceでは追跡対象refと`resolvedCommit`を比較します。
|
|
126
|
+
npm sourceでは、宣言した完全固定バージョンとインストール済みパッケージをネットワークなしで比較します。
|
|
115
127
|
|
|
116
128
|
### 固定したコミットからの復元
|
|
117
129
|
|
|
@@ -120,9 +132,9 @@ sb3-toolchain extensions sync app
|
|
|
120
132
|
sb3-toolchain check app
|
|
121
133
|
```
|
|
122
134
|
|
|
123
|
-
`sync
|
|
124
|
-
JavaScriptと任意の
|
|
125
|
-
|
|
135
|
+
`sync`は変更可能なブランチやタグを解決しません。GitHub sourceは`resolvedCommit`からダウンロードし、
|
|
136
|
+
npm sourceは最寄りの親`node_modules`へ導入済みの完全固定パッケージから読み込みます。JavaScriptと任意の
|
|
137
|
+
APIマニフェストが記録済みIDおよびSHA-256値に一致する場合に限り、ローカルファイルを置き換えます。
|
|
126
138
|
|
|
127
139
|
### 追跡対象refの更新
|
|
128
140
|
|
|
@@ -136,6 +148,10 @@ git diff -- app
|
|
|
136
148
|
IDを省略すると、管理対象の全機能拡張を1回のトランザクションで更新します。ダウンロードまたは検証が1つでも
|
|
137
149
|
失敗した場合、ファイルもメタデータも変更しません。
|
|
138
150
|
|
|
151
|
+
npm sourceでは、最初にプロジェクトのパッケージマネージャーで新しい完全固定バージョンを導入し、続けて
|
|
152
|
+
`extensions status`と`extensions update`を実行します。updateは導入済み成果物をコピーし、パッケージの
|
|
153
|
+
`version`とintegrityを記録します。sb3-toolchain自身はnpm registryへ問い合わせません。
|
|
154
|
+
|
|
139
155
|
`source.apiManifest`が存在する場合、同じ解決済みコミットからJavaScriptとAPIマニフェストをダウンロードします。
|
|
140
156
|
互換性のある追加は報告されます。ブロックの削除、ブロック種別の変更、引数契約の変更、参照中メニューの削除、
|
|
141
157
|
`acceptReporters`の変更は、インストール前に拒否されます。未参照メニューの削除には互換性があります。
|
|
@@ -148,8 +164,8 @@ sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
|
|
|
148
164
|
バージョン付きマニフェスト契約、分類表、既定OFFの動作、ロールバックについては、
|
|
149
165
|
[`extension-api-compatibility.md`](extension-api-compatibility.md)を参照してください。
|
|
150
166
|
|
|
151
|
-
更新PRでは、`resolvedCommit`、JavaScriptとマニフェストのintegrity
|
|
152
|
-
|
|
167
|
+
更新PRでは、`resolvedCommit`またはnpmの`version`、JavaScriptとマニフェストのintegrity、互換性パス、
|
|
168
|
+
両成果物をまとめて確認し、生成SB3で機能拡張の主要機能をテストします。
|
|
153
169
|
|
|
154
170
|
## 機能拡張IDの移行
|
|
155
171
|
|