@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
package/README.ja.md
ADDED
|
@@ -0,0 +1,151 @@
|
|
|
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の固定コミットまたはインストール済みnpmパッケージの完全固定バージョンから埋め込み機能拡張を管理し、
|
|
13
|
+
SHA-256ハッシュをオフラインで検証
|
|
14
|
+
- 埋め込みJavaScriptを置き換える前に、バージョン付き機能拡張APIマニフェストを任意で比較
|
|
15
|
+
- 元のJavaScriptを削除せず、複数の機能拡張を1つの権限単位へ静的にbundleし、展開ソースまたは
|
|
16
|
+
bundle済みSB3から復元
|
|
17
|
+
- ZIPエントリ順、タイムスタンプ、圧縮設定を固定した決定的ビルド
|
|
18
|
+
- 全ターゲットのスクリプトをTurboWarp風の決定的な「きれいにする」配置へ任意で整理
|
|
19
|
+
- import時に未コミットのGit変更を保護
|
|
20
|
+
- トランザクションによる置換とロールバックで既存出力を保護
|
|
21
|
+
- CLIとJavaScript APIの両方を提供
|
|
22
|
+
|
|
23
|
+
## 必要環境
|
|
24
|
+
|
|
25
|
+
- Node.js 22.12.0以降
|
|
26
|
+
- pnpm 11
|
|
27
|
+
|
|
28
|
+
## インストール
|
|
29
|
+
|
|
30
|
+
再現可能なインストールのため、検証済みのnpmバージョンを固定します。
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.5.0
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## クイックスタート
|
|
37
|
+
|
|
38
|
+
TurboWarpで保存したSB3を展開して検証し、再ビルドします。
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
sb3-toolchain import tmp/project.sb3 --output app
|
|
42
|
+
sb3-toolchain check app
|
|
43
|
+
sb3-toolchain build app --output dist/project.sb3
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
プロジェクトリポジトリに推奨する信頼できる唯一の情報源、再import、置換保護、機能拡張更新、CIの
|
|
47
|
+
ワークフローについては、[`docs/ja/workflows.md`](docs/ja/workflows.md)を参照してください。
|
|
48
|
+
|
|
49
|
+
## JavaScript API
|
|
50
|
+
|
|
51
|
+
```js
|
|
52
|
+
import {readFile} from 'node:fs/promises';
|
|
53
|
+
|
|
54
|
+
import {
|
|
55
|
+
buildSb3,
|
|
56
|
+
bundleExtensions,
|
|
57
|
+
createDeterministicSb3,
|
|
58
|
+
extensionIntegrity,
|
|
59
|
+
extensionStatus,
|
|
60
|
+
importSb3,
|
|
61
|
+
migrateExtensionId,
|
|
62
|
+
planExtensionIdMigration,
|
|
63
|
+
syncExtensions,
|
|
64
|
+
unbundleSb3,
|
|
65
|
+
unbundleExtensions,
|
|
66
|
+
updateExtensions,
|
|
67
|
+
validateSb3Source,
|
|
68
|
+
} from '@kubohiroya/sb3-toolchain';
|
|
69
|
+
|
|
70
|
+
await importSb3({
|
|
71
|
+
inputPath: 'tmp/project.sb3',
|
|
72
|
+
outputDirectory: 'app',
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
await validateSb3Source('app');
|
|
76
|
+
|
|
77
|
+
await buildSb3({
|
|
78
|
+
sourceDirectory: 'app',
|
|
79
|
+
outputPath: 'dist/project.sb3',
|
|
80
|
+
// 生成SB3だけを整理済みブロック座標にする場合に明示的に有効化します。
|
|
81
|
+
cleanUpBlocks: true,
|
|
82
|
+
});
|
|
83
|
+
|
|
84
|
+
const {archive} = await createDeterministicSb3('app', {cleanUpBlocks: true});
|
|
85
|
+
|
|
86
|
+
const integrity = extensionIntegrity(await readFile('app/extensions/example.js'));
|
|
87
|
+
|
|
88
|
+
const statuses = await extensionStatus('app');
|
|
89
|
+
const migration = await planExtensionIdMigration({
|
|
90
|
+
sourceDirectory: 'app',
|
|
91
|
+
fromId: 'oldId',
|
|
92
|
+
toId: 'newid',
|
|
93
|
+
});
|
|
94
|
+
await migrateExtensionId({
|
|
95
|
+
sourceDirectory: 'app',
|
|
96
|
+
fromId: 'oldId',
|
|
97
|
+
toId: 'newid',
|
|
98
|
+
yes: true,
|
|
99
|
+
});
|
|
100
|
+
await syncExtensions({sourceDirectory: 'app', yes: true});
|
|
101
|
+
await updateExtensions({
|
|
102
|
+
sourceDirectory: 'app',
|
|
103
|
+
extensionId: 'oldId',
|
|
104
|
+
migrateToId: 'newid',
|
|
105
|
+
sourceArtifact: 'dist/newid.js',
|
|
106
|
+
apiManifestArtifact: 'dist/newid.manifest.json',
|
|
107
|
+
yes: true,
|
|
108
|
+
});
|
|
109
|
+
// After reviewing a reported breaking API change, opt in explicitly:
|
|
110
|
+
await updateExtensions({sourceDirectory: 'app', allowBreakingApi: true, yes: true});
|
|
111
|
+
await bundleExtensions({
|
|
112
|
+
sourceDirectory: 'app',
|
|
113
|
+
bundleId: 'projectbundle',
|
|
114
|
+
bundleName: 'Project Extension Bundle',
|
|
115
|
+
extensionIds: ['extensionone', 'extensiontwo'],
|
|
116
|
+
yes: true,
|
|
117
|
+
});
|
|
118
|
+
await unbundleExtensions({
|
|
119
|
+
sourceDirectory: 'app',
|
|
120
|
+
bundleId: 'projectbundle',
|
|
121
|
+
yes: true,
|
|
122
|
+
});
|
|
123
|
+
await unbundleSb3({
|
|
124
|
+
inputPath: 'dist/project.sb3',
|
|
125
|
+
outputPath: 'dist/project.unbundled.sb3',
|
|
126
|
+
bundleId: 'projectbundle',
|
|
127
|
+
yes: true,
|
|
128
|
+
});
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## ドキュメント
|
|
132
|
+
|
|
133
|
+
- [`docs/ja/workflows.md`](docs/ja/workflows.md): SB3ソースと機能拡張を管理するワークフロー
|
|
134
|
+
- [`docs/ja/source-format-v1.md`](docs/ja/source-format-v1.md): 展開ソース形式と決定的出力
|
|
135
|
+
- [`docs/ja/extension-id-migration.md`](docs/ja/extension-id-migration.md): プロジェクトで使用中の機能拡張IDの移行
|
|
136
|
+
- [`docs/ja/extension-api-compatibility.md`](docs/ja/extension-api-compatibility.md): 機能拡張更新時の任意の静的API互換性検査
|
|
137
|
+
- [`docs/ja/extension-bundles.md`](docs/ja/extension-bundles.md): 1つの権限単位への静的bundleと可逆的なunbundle
|
|
138
|
+
|
|
139
|
+
## 開発
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
pnpm install
|
|
143
|
+
pnpm check
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## ライセンス
|
|
147
|
+
|
|
148
|
+
[Mozilla Public License 2.0](LICENSE)
|
|
149
|
+
|
|
150
|
+
この実装は、[`kubohiroya/tmpose-kamishibai`](https://github.com/kubohiroya/tmpose-kamishibai)
|
|
151
|
+
向けに開発された一般的な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
|
|
|
@@ -7,18 +9,17 @@ expanded sources and rebuilding bit-for-bit identical SB3 files from the same in
|
|
|
7
9
|
|
|
8
10
|
- Safely expand an SB3 into formatted `project.source.json`, assets, and embedded extensions
|
|
9
11
|
- Validate asset references, MD5 hashes, ZIP entries, and embedded extension mappings
|
|
10
|
-
-
|
|
12
|
+
- Manage embedded extensions from pinned GitHub commits or exact installed npm package versions and
|
|
13
|
+
verify their SHA-256 hashes offline
|
|
11
14
|
- Optionally compare versioned extension API manifests before replacing embedded JavaScript
|
|
12
15
|
- Statically bundle multiple extensions into one permission unit without deleting their original
|
|
13
16
|
JavaScript, then restore them from either the expanded source or the bundled SB3
|
|
14
17
|
- Produce deterministic builds with fixed ZIP entry order, timestamps, and compression settings
|
|
18
|
+
- Optionally lay out every target's scripts in a deterministic TurboWarp-style cleaned arrangement
|
|
15
19
|
- Protect uncommitted Git changes when importing
|
|
16
20
|
- Protect existing output through transactional replacement and rollback
|
|
17
21
|
- Provide both a CLI and a JavaScript API
|
|
18
22
|
|
|
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
23
|
## Requirements
|
|
23
24
|
|
|
24
25
|
- Node.js 22.12.0 or later
|
|
@@ -29,7 +30,7 @@ TurboWarp Packager are outside the scope of this package.
|
|
|
29
30
|
Pin the verified npm version for reproducible installation.
|
|
30
31
|
|
|
31
32
|
```bash
|
|
32
|
-
pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.
|
|
33
|
+
pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.5.0
|
|
33
34
|
```
|
|
34
35
|
|
|
35
36
|
## Quick start
|
|
@@ -76,9 +77,11 @@ await validateSb3Source('app');
|
|
|
76
77
|
await buildSb3({
|
|
77
78
|
sourceDirectory: 'app',
|
|
78
79
|
outputPath: 'dist/project.sb3',
|
|
80
|
+
// Opt in to cleaned block coordinates in the generated SB3 only:
|
|
81
|
+
cleanUpBlocks: true,
|
|
79
82
|
});
|
|
80
83
|
|
|
81
|
-
const {archive} = await createDeterministicSb3('app');
|
|
84
|
+
const {archive} = await createDeterministicSb3('app', {cleanUpBlocks: true});
|
|
82
85
|
|
|
83
86
|
const integrity = extensionIntegrity(await readFile('app/extensions/example.js'));
|
|
84
87
|
|
|
@@ -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
|
|
@@ -178,6 +180,13 @@ sequenceDiagram
|
|
|
178
180
|
|
|
179
181
|
A->>W: startHats("alpha_whenReady")
|
|
180
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
|
|
181
190
|
```
|
|
182
191
|
|
|
183
192
|
### Data transformations
|
|
@@ -190,6 +199,7 @@ sequenceDiagram
|
|
|
190
199
|
| Stored project opcode | `alpha_doSomething` | `projectbundle_alpha__doSomething` |
|
|
191
200
|
| Menu and custom-field names | Member-local names | `memberId__` namespace |
|
|
192
201
|
| `startHats()` opcode | `alpha_whenReady` | `projectbundle_alpha__whenReady` |
|
|
202
|
+
| `getOpcodeFunction()` | `beta_echo` | `projectbundle_beta__echo` |
|
|
193
203
|
| Extension storage | `storage.alpha`, `storage.beta` | `storage.projectbundle.components.alpha/beta` |
|
|
194
204
|
| Block IDs and graph links | Original IDs and `next`/`parent`/`inputs` | Unchanged |
|
|
195
205
|
|
|
@@ -220,18 +230,28 @@ behavior. The current static-bundle contract requires all of the following:
|
|
|
220
230
|
|
|
221
231
|
The bundle namespaces ordinary commands, reporters, booleans, events, buttons, labels, static and
|
|
222
232
|
dynamic menus, custom fields, and global and target extension storage. Calls from child extensions
|
|
223
|
-
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.
|
|
224
243
|
|
|
225
244
|
The bundle preserves the `members` order from the manifest and the block-definition order within
|
|
226
245
|
each member's `getInfo().blocks`. In the TurboWarp Editor palette, each group begins with a decorated
|
|
227
246
|
LABEL heading in this form:
|
|
228
247
|
|
|
229
248
|
```text
|
|
230
|
-
◆
|
|
249
|
+
◆ <name> [<memberId>] ◆
|
|
231
250
|
```
|
|
232
251
|
|
|
233
|
-
|
|
234
|
-
machine-readable
|
|
252
|
+
Putting the member name first keeps it visible in TurboWarp's narrow palette. Two consecutive `---`
|
|
253
|
+
separators divide member groups. A generated LABEL also carries the following machine-readable
|
|
254
|
+
metadata:
|
|
235
255
|
|
|
236
256
|
```js
|
|
237
257
|
{
|
|
@@ -242,6 +262,24 @@ machine-readable metadata:
|
|
|
242
262
|
}
|
|
243
263
|
```
|
|
244
264
|
|
|
265
|
+
When a member's `getInfo()` returns a non-empty string [`docsURI`](https://docs.turbowarp.org/development/extensions/assorted-apis#docsuri),
|
|
266
|
+
the bundle inserts an `Open Documentation` button immediately after that member's heading. It uses TurboWarp's native
|
|
267
|
+
`OPEN_EXTENSION_DOCS` callback, so it preserves the normal `docsURI` behavior instead of delegating
|
|
268
|
+
to extension code. The generated button carries separate metadata and safely XML-escapes the URI:
|
|
269
|
+
|
|
270
|
+
```js
|
|
271
|
+
{
|
|
272
|
+
sb3Toolchain: {
|
|
273
|
+
docsURI,
|
|
274
|
+
kind: 'bundle-member-docs',
|
|
275
|
+
memberId,
|
|
276
|
+
},
|
|
277
|
+
}
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
No button is inserted for a member without `docsURI`. Member-provided XML blocks remain unsupported;
|
|
281
|
+
the tool generates only this narrowly defined documentation button XML.
|
|
282
|
+
|
|
245
283
|
LABEL entries and separators originally defined by a member are preserved unchanged and in their
|
|
246
284
|
original positions. The decorated bundle heading and wider double separator therefore remain
|
|
247
285
|
visually distinct from an original heading or ordinary separator. A tool can identify the generated
|
|
@@ -252,14 +290,15 @@ The resulting palette has this visual hierarchy:
|
|
|
252
290
|
|
|
253
291
|
```text
|
|
254
292
|
┌─ Project Extension Bundle ─────────────────────────────┐
|
|
255
|
-
│ ◆
|
|
293
|
+
│ ◆ Alpha Tools [alpha] ◆ │ ← generated heading
|
|
294
|
+
│ Open Documentation │ ← generated docsURI button
|
|
256
295
|
│ alpha block 1 │
|
|
257
296
|
│ Alpha original heading │ ← original LABEL
|
|
258
297
|
│ │ ← original separator
|
|
259
298
|
│ alpha block 2 │
|
|
260
299
|
│ │
|
|
261
300
|
│ │ ← generated double separator
|
|
262
|
-
│ ◆
|
|
301
|
+
│ ◆ Beta Tools [beta] ◆ │ ← generated heading
|
|
263
302
|
│ beta block 1 │
|
|
264
303
|
└────────────────────────────────────────────────────────┘
|
|
265
304
|
```
|
|
@@ -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.
|