@kubohiroya/sb3-toolchain 0.7.0 → 0.8.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 CHANGED
@@ -31,7 +31,7 @@ Scratch 3およびTurboWarpの`.sb3`プロジェクトを、Gitで差分を確
31
31
  再現可能なインストールのため、検証済みのnpmバージョンを固定します。
32
32
 
33
33
  ```bash
34
- pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.7.0
34
+ pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.8.0
35
35
  ```
36
36
 
37
37
  ## クイックスタート
package/README.md CHANGED
@@ -32,7 +32,7 @@ expanded sources and rebuilding bit-for-bit identical SB3 files from the same in
32
32
  Pin the verified npm version for reproducible installation.
33
33
 
34
34
  ```bash
35
- pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.7.0
35
+ pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.8.0
36
36
  ```
37
37
 
38
38
  ## Quick start
@@ -22,7 +22,7 @@ flowchart LR
22
22
  subgraph Output["Generated bundled SB3"]
23
23
  BundledProject["project.json<br/>namespaced opcodes"]
24
24
  Composite["one composite extension<br/>one register() call"]
25
- Capsule["recovery capsule<br/>original extension data"]
25
+ Capsule["optional recovery capsule<br/>original extension data"]
26
26
  end
27
27
 
28
28
  TurboWarp["TurboWarp Editor<br/>one permission prompt"]
@@ -38,8 +38,7 @@ flowchart LR
38
38
  ```
39
39
 
40
40
  The expanded source always retains the individual extensions. Bundling changes only the generated
41
- SB3, and the recovery capsule makes that generated artifact reversible when its safety conditions
42
- remain satisfied.
41
+ SB3. Recovery data is opt-in when direct restoration from that generated artifact is required.
43
42
 
44
43
  ## What problem it solves
45
44
 
@@ -74,7 +73,7 @@ extension to authorize and load.
74
73
  | Create one composite runtime extension from several members | Disable or bypass TurboWarp's permission prompt |
75
74
  | Rewrite generated project references to collision-free namespaces | Rewrite the authoritative source project in place |
76
75
  | Preserve and delegate each member's original implementation | Flatten all member classes into one manually merged class |
77
- | Embed recovery data for direct SB3 unbundling | Guarantee compatibility for arbitrary dynamic extension code |
76
+ | Optionally embed recovery data for direct SB3 unbundling | Guarantee compatibility for arbitrary dynamic extension code |
78
77
  | Reject transformations that cannot be classified safely | Execute extension JavaScript during the build |
79
78
 
80
79
  ## Internal architecture
@@ -147,7 +146,7 @@ projectbundle.js
147
146
  │ ├── generated palette headings and separators
148
147
  │ └── handlers that delegate to captured member instances
149
148
  ├── one real Scratch.extensions.register() call
150
- └── SB3-Toolchain-Reversible-Bundle-v1 recovery capsule
149
+ └── optional SB3-Toolchain-Reversible-Bundle-v1 recovery capsule
151
150
  ```
152
151
 
153
152
  The original scripts still execute their normal initialization code at runtime. Their calls to
@@ -352,9 +351,14 @@ Only `projectbundle` appears in `extensions` and `extensionURLs`, and the genera
352
351
  `Scratch.extensions.register` once. The initial comments in that JavaScript list every member's
353
352
  name, ID, author, description, and license so the user can inspect them before granting permission.
354
353
 
355
- The end of the JavaScript contains an `SB3-Toolchain-Reversible-Bundle-v1` recovery capsule. The
356
- capsule records each original member data URL, member order, and the original `extensions` and
357
- `extensionURLs` order.
354
+ By default, the JavaScript omits duplicate recovery data. First confirm that every member license
355
+ permits modification and combination, and keep all required notices and corresponding source
356
+ available. The bundle header, member code, block icons, opcode namespaces, and storage behavior are
357
+ unchanged.
358
+
359
+ Set `"recoveryCapsule": true` on a bundle, or pass `--include-recovery-capsule` while configuring it,
360
+ to append an `SB3-Toolchain-Reversible-Bundle-v1` capsule. It records each original member data URL,
361
+ member order, and the original `extensions` and `extensionURLs` order, at the cost of a larger output.
358
362
 
359
363
  ## Restore from expanded source
360
364
 
@@ -401,8 +405,9 @@ accidentally.
401
405
 
402
406
  ## Restore a bundled SB3 directly
403
407
 
404
- A bundled SB3 containing a recovery capsule can be unbundled without the expanded source. The
405
- command is a dry run unless `--yes` is supplied.
408
+ A bundled SB3 containing an explicitly enabled recovery capsule can be unbundled without the expanded
409
+ source. The default compact bundle must instead be restored from its authoritative expanded source.
410
+ The command is a dry run unless `--yes` is supplied.
406
411
 
407
412
  ```bash
408
413
  sb3-toolchain extensions unbundle \
@@ -453,8 +458,9 @@ flowchart TD
453
458
  The tool refuses the operation without modifying the output instead of guessing when any of the
454
459
  following conditions apply:
455
460
 
456
- - The target data URL has no `SB3-Toolchain-Reversible-Bundle-v1` capsule because the bundle was
457
- produced before recovery capsules were introduced, by another tool, or by hand
461
+ - The target data URL has no `SB3-Toolchain-Reversible-Bundle-v1` capsule because recovery was not
462
+ explicitly enabled, the bundle was produced before recovery capsules were introduced, or it was
463
+ produced by another tool or by hand
458
464
  - The bundle data URL or capsule was removed, corrupted, or duplicated; its format version is not
459
465
  supported; or its bundle ID, member ID, and original JavaScript header ID do not agree
460
466
  - The ID set or order in `project.extensions` or `extensionURLs` changed after bundling. For example,
@@ -21,7 +21,7 @@ flowchart LR
21
21
  subgraph Output["生成されたbundle済みSB3"]
22
22
  BundledProject["project.json<br/>名前空間化されたopcode"]
23
23
  Composite["1つの複合機能拡張<br/>1回のregister()呼び出し"]
24
- Capsule["復元カプセル<br/>元の機能拡張データ"]
24
+ Capsule["任意の復元カプセル<br/>元の機能拡張データ"]
25
25
  end
26
26
 
27
27
  TurboWarp["TurboWarp Editor<br/>1回の権限確認"]
@@ -36,8 +36,8 @@ flowchart LR
36
36
  Composite --> TurboWarp
37
37
  ```
38
38
 
39
- 展開ソースには、常に個別機能拡張が保持されます。bundleによって変わるのは生成SB3だけです。安全条件を満たす
40
- 間は、復元カプセルによって生成成果物を元に戻せます。
39
+ 展開ソースには、常に個別機能拡張が保持されます。bundleによって変わるのは生成SB3だけです。生成成果物から
40
+ 直接復元する必要がある場合に限り、復元データを明示的に追加します。
41
41
 
42
42
  ## 解決する問題
43
43
 
@@ -71,7 +71,7 @@ flowchart LR
71
71
  | 複数メンバーから1つの複合ランタイム機能拡張を作成 | TurboWarpの権限確認を無効化または回避 |
72
72
  | 生成プロジェクトの参照を衝突しない名前空間へ書き換え | 信頼できる情報源であるプロジェクトを直接書き換え |
73
73
  | 各メンバーの元の実装を保持して処理を委譲 | すべてのメンバークラスを手作業で1クラスへ平坦化 |
74
- | SB3を直接unbundleするための復元データを埋め込み | 任意の動的な機能拡張コードに対する互換性を保証 |
74
+ | SB3を直接unbundleする復元データを任意で埋め込み | 任意の動的な機能拡張コードに対する互換性を保証 |
75
75
  | 安全に分類できない変換を拒否 | ビルド中に機能拡張JavaScriptを実行 |
76
76
 
77
77
  ## 内部アーキテクチャ
@@ -144,7 +144,7 @@ projectbundle.js
144
144
  │ ├── 生成されたパレット見出しとseparator
145
145
  │ └── 捕捉したメンバーインスタンスへ委譲するhandler
146
146
  ├── 実際のScratch.extensions.register()呼び出し1回
147
- └── SB3-Toolchain-Reversible-Bundle-v1復元カプセル
147
+ └── 任意のSB3-Toolchain-Reversible-Bundle-v1復元カプセル
148
148
  ```
149
149
 
150
150
  元のスクリプトは、ランタイムで通常の初期化コードを引き続き実行します。各スクリプトの
@@ -342,8 +342,13 @@ bundleの読み込みを拒否します。
342
342
  `Scratch.extensions.register`を1回呼び出します。そのJavaScriptの先頭コメントには全メンバーの名前、ID、
343
343
  作者、説明、ライセンスが列挙され、ユーザーは権限を許可する前に確認できます。
344
344
 
345
- JavaScriptの末尾には`SB3-Toolchain-Reversible-Bundle-v1`復元カプセルが含まれます。カプセルは各メンバーの
346
- 元のdata URL、メンバー順、元の`extensions`と`extensionURLs`の順序を記録します。
345
+ 既定では、JavaScriptから重複する復元データを省略します。すべてのメンバーライセンスが改変と結合を許可する
346
+ ことを先に確認し、必要な通知と対応ソースを利用可能な状態で保持してください。bundleヘッダー、メンバーコード、
347
+ ブロックアイコン、opcode名前空間、ストレージ動作は変わりません。
348
+
349
+ bundleに`"recoveryCapsule": true`を指定するか、設定時に`--include-recovery-capsule`を渡すと、末尾に
350
+ `SB3-Toolchain-Reversible-Bundle-v1`カプセルを追加します。カプセルは各メンバーの元のdata URL、メンバー順、
351
+ 元の`extensions`と`extensionURLs`の順序を記録しますが、出力サイズは増加します。
347
352
 
348
353
  ## 展開ソースからの復元
349
354
 
@@ -388,8 +393,8 @@ sb3-toolchain build app --output dist/project.sb3 --yes
388
393
 
389
394
  ## bundle済みSB3の直接復元
390
395
 
391
- 復元カプセルを含むbundle済みSB3は、展開ソースがなくてもunbundleできます。`--yes`を指定しない限り、
392
- コマンドはdry runです。
396
+ 明示的に復元カプセルを含めたbundle済みSB3は、展開ソースがなくてもunbundleできます。既定のcompact bundleは、
397
+ 信頼できる展開ソースから復元する必要があります。`--yes`を指定しない限り、コマンドはdry runです。
393
398
 
394
399
  ```bash
395
400
  sb3-toolchain extensions unbundle \
@@ -438,8 +443,8 @@ flowchart TD
438
443
 
439
444
  次のいずれかの条件に該当する場合、ツールは推測せず、出力を変更せずに操作を拒否します。
440
445
 
441
- - 対象data URLに`SB3-Toolchain-Reversible-Bundle-v1`カプセルがない。復元カプセル導入前、別のツール、
442
- または手作業でbundleが生成された場合が該当する
446
+ - 対象data URLに`SB3-Toolchain-Reversible-Bundle-v1`カプセルがない。復元を明示的に有効化していない、
447
+ 復元カプセル導入前、別のツール、または手作業でbundleが生成された場合が該当する
443
448
  - bundle data URLまたはカプセルが削除、破損、重複している、形式バージョンが未対応、またはbundle ID、
444
449
  メンバーID、元のJavaScriptヘッダーIDが一致しない
445
450
  - bundle後に`project.extensions`または`extensionURLs`内のID集合や順序が変わった。たとえば別の機能拡張を
@@ -167,15 +167,19 @@ APIマニフェストファイルは展開ソースの検証入力であり、SB
167
167
  - `members`: 2つ以上の個別機能拡張ID。順序によってブロックとメニューの合成順が決まる。パレットでは、
168
168
  メタデータを持つ装飾済みbundle LABEL見出しとグループ間の二重separatorが追加される一方、元の機能拡張の
169
169
  LABELエントリとseparatorは変更されない
170
+ - `recoveryCapsule`: 任意の真偽値で、既定値は`false`。追加サイズを許容でき、生成SB3単体からの直接unbundleが
171
+ 必要な場合に限り`true`を指定する
170
172
 
171
173
  1つのメンバーを複数のbundleに所属させることはできません。個別エントリ、個別JavaScript、`source`、
172
174
  `project.source.json`が引き続き信頼できる情報源です。`build`は各元opcodeに`memberId + "__"`を加え、
173
175
  出力側の`project.json`のopcode、`extensions`、`extensionURLs`、機能拡張ストレージだけをbundle IDに変更します。
174
176
  埋め込まれるbundle JavaScriptのdata URLは1つです。
175
177
 
176
- bundle JavaScriptの末尾には、元の個別data URLと機能拡張の順序を格納した形式1の復元カプセルが含まれます。
177
- 設定を削除するか、そのカプセルを含む生成SB3に対して`extensions unbundle`を実行すると、通常の出力へ
178
- 復元できます。互換性契約と復元手順については、[`extension-bundles.md`](extension-bundles.md)を参照してください。
178
+ 既定では、メンバーコードとヘッダー通知を生成JavaScriptに残したまま、重複する復元データを省略します。
179
+ `recoveryCapsule: true`では、元の個別data URLと機能拡張の順序を格納した形式1のカプセルを追加します。
180
+ 設定を削除すれば展開ソースから常に通常出力へ戻せますが、生成SB3を直接`extensions unbundle`するには
181
+ カプセルが必要です。互換性契約と復元手順については、
182
+ [`extension-bundles.md`](extension-bundles.md)を参照してください。
179
183
 
180
184
  ## アセット
181
185
 
@@ -172,15 +172,17 @@ only in the generated SB3.
172
172
  - `id`: composite extension ID in TurboWarp's `[a-z0-9]+` form that does not collide with an individual extension
173
173
  - `name`: single-line name displayed in the permission prompt and extension category
174
174
  - `members`: two or more individual extension IDs; their order defines block and menu composition order. The palette receives a decorated, metadata-bearing bundle LABEL heading and a double separator between groups, while LABEL entries and separators from the original extensions remain unchanged
175
+ - `recoveryCapsule`: optional boolean, default `false`. Set it to `true` only when the extra size is acceptable and direct unbundling from the generated SB3 is required
175
176
 
176
177
  A member cannot belong to more than one bundle. Individual entries, individual JavaScript, `source`,
177
178
  and `project.source.json` remain authoritative. `build` adds `memberId + "__"` to each original opcode
178
179
  and changes only the output `project.json` opcodes, `extensions`, `extensionURLs`, and extension storage
179
180
  to the bundle ID. It embeds one bundle JavaScript data URL.
180
181
 
181
- The end of the bundle JavaScript contains a format 1 recovery capsule with the original individual
182
- data URLs and extension order. Removing the configuration or running `extensions unbundle` against a
183
- generated SB3 containing that capsule restores the ordinary output. See
182
+ By default, the bundle omits duplicate recovery data while leaving member code and header notices in
183
+ the generated JavaScript. `recoveryCapsule: true` adds a format 1 capsule with the original individual
184
+ data URLs and extension order. Removing the configuration always restores the ordinary output from
185
+ expanded source; direct `extensions unbundle` of the generated SB3 requires the capsule. See
184
186
  [`extension-bundles.md`](extension-bundles.md) for the compatibility contract and restoration steps.
185
187
 
186
188
  ## Assets
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/sb3-toolchain",
3
- "version": "0.7.0",
3
+ "version": "0.8.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",
package/src/cli.js CHANGED
@@ -33,7 +33,7 @@ export function usage() {
33
33
  sb3-toolchain extensions sync SOURCE_DIR [--yes]
34
34
  sb3-toolchain extensions update SOURCE_DIR [EXTENSION_ID] [--migrate-id NEW_ID] [--artifact PATH] [--api-manifest-artifact PATH] [--allow-breaking-api --yes]
35
35
  sb3-toolchain extensions migrate-id SOURCE_DIR --from OLD_ID --to NEW_ID [--yes]
36
- sb3-toolchain extensions bundle SOURCE_DIR --id BUNDLE_ID --name NAME [EXTENSION_ID ...] [--yes]
36
+ sb3-toolchain extensions bundle SOURCE_DIR --id BUNDLE_ID --name NAME [EXTENSION_ID ...] [--include-recovery-capsule] [--yes]
37
37
  sb3-toolchain extensions unbundle SOURCE_DIR BUNDLE_ID [--yes]
38
38
  sb3-toolchain extensions unbundle INPUT.sb3 BUNDLE_ID --output OUTPUT.sb3 [--yes]
39
39
 
@@ -293,6 +293,7 @@ function parseExtensionIdMigrationArguments(arguments_) {
293
293
  function parseExtensionBundleArguments(arguments_) {
294
294
  let bundleId;
295
295
  let bundleName;
296
+ let recoveryCapsule = false;
296
297
  let sourceDirectory;
297
298
  const extensionIds = [];
298
299
  let yes = false;
@@ -307,6 +308,8 @@ function parseExtensionBundleArguments(arguments_) {
307
308
  index += 1;
308
309
  } else if (argument === '--yes') {
309
310
  yes = true;
311
+ } else if (argument === '--include-recovery-capsule') {
312
+ recoveryCapsule = true;
310
313
  } else {
311
314
  assert(!argument.startsWith('-'), `Unknown option: ${argument}`);
312
315
  if (!sourceDirectory) {
@@ -329,6 +332,7 @@ function parseExtensionBundleArguments(arguments_) {
329
332
  bundleName,
330
333
  command: 'extensions',
331
334
  extensionIds,
335
+ recoveryCapsule,
332
336
  sourceDirectory,
333
337
  yes,
334
338
  };
@@ -598,6 +602,7 @@ export async function runCli(
598
602
  bundleId: options.bundleId,
599
603
  bundleName: options.bundleName,
600
604
  extensionIds: options.extensionIds,
605
+ recoveryCapsule: options.recoveryCapsule,
601
606
  sourceDirectory: options.sourceDirectory,
602
607
  yes: options.yes,
603
608
  });
package/src/constants.js CHANGED
@@ -1,4 +1,4 @@
1
1
  // SPDX-License-Identifier: MPL-2.0
2
2
 
3
3
  export const packageName = '@kubohiroya/sb3-toolchain';
4
- export const packageVersion = '0.7.0';
4
+ export const packageVersion = '0.8.0';
@@ -56,11 +56,13 @@ async function configurationContext({
56
56
  bundleId,
57
57
  bundleName,
58
58
  extensionIds,
59
+ recoveryCapsule,
59
60
  sourceDirectory,
60
61
  willReplace,
61
62
  }) {
62
63
  validateBundleId(bundleId);
63
64
  validateBundleName(bundleName);
65
+ assert(typeof recoveryCapsule === 'boolean', 'recoveryCapsule must be a boolean.');
64
66
  const source = await inspectConfigurationSource(sourceDirectory, willReplace);
65
67
  const extensionManifest = await readExtensionManifest(source);
66
68
  const existingBundles = validateExtensionBundleConfigurations(
@@ -81,7 +83,12 @@ async function configurationContext({
81
83
  const candidateManifest = structuredClone(extensionManifest);
82
84
  candidateManifest.extensionBundles = [
83
85
  ...existingBundles,
84
- {id: bundleId, members, name: bundleName},
86
+ {
87
+ id: bundleId,
88
+ members,
89
+ name: bundleName,
90
+ ...(recoveryCapsule === true ? {recoveryCapsule: true} : {}),
91
+ },
85
92
  ];
86
93
  const extensionBundles = validateExtensionBundleConfigurations(
87
94
  candidateManifest.extensionBundles,
@@ -97,11 +104,18 @@ async function configurationContext({
97
104
  return {buildPlan, candidateManifest, configuredBundle, extensionManifest, source};
98
105
  }
99
106
 
100
- export async function planExtensionBundle({bundleId, bundleName, extensionIds, sourceDirectory}) {
107
+ export async function planExtensionBundle({
108
+ bundleId,
109
+ bundleName,
110
+ extensionIds,
111
+ recoveryCapsule = false,
112
+ sourceDirectory,
113
+ }) {
101
114
  const context = await configurationContext({
102
115
  bundleId,
103
116
  bundleName,
104
117
  extensionIds,
118
+ recoveryCapsule,
105
119
  sourceDirectory,
106
120
  willReplace: false,
107
121
  });
@@ -113,6 +127,7 @@ export async function planExtensionBundle({bundleId, bundleName, extensionIds, s
113
127
  components: context.configuredBundle.components.map((component) => component.metadata),
114
128
  counts: context.configuredBundle.counts,
115
129
  members: [...context.configuredBundle.bundle.members],
130
+ recoveryCapsule: context.configuredBundle.bundle.recoveryCapsule === true,
116
131
  sourceDirectory: context.source.resolvedSourceDirectory,
117
132
  };
118
133
  }
@@ -176,6 +191,7 @@ export async function bundleExtensions({
176
191
  bundleId,
177
192
  bundleName,
178
193
  extensionIds,
194
+ recoveryCapsule = false,
179
195
  sourceDirectory,
180
196
  yes = false,
181
197
  }) {
@@ -183,6 +199,7 @@ export async function bundleExtensions({
183
199
  bundleId,
184
200
  bundleName,
185
201
  extensionIds,
202
+ recoveryCapsule,
186
203
  sourceDirectory,
187
204
  willReplace: yes,
188
205
  });
@@ -192,6 +209,7 @@ export async function bundleExtensions({
192
209
  components: context.configuredBundle.components.map((component) => component.metadata),
193
210
  counts: context.configuredBundle.counts,
194
211
  members: [...context.configuredBundle.bundle.members],
212
+ recoveryCapsule: context.configuredBundle.bundle.recoveryCapsule === true,
195
213
  sourceDirectory: context.source.resolvedSourceDirectory,
196
214
  };
197
215
  if (!yes) {
@@ -55,6 +55,10 @@ export function validateExtensionBundleConfigurations(extensionBundles, extensio
55
55
  Array.isArray(bundle.members) && bundle.members.length >= 2,
56
56
  `Extension bundle ${bundle.id} must contain at least two members.`,
57
57
  );
58
+ assert(
59
+ bundle.recoveryCapsule === undefined || typeof bundle.recoveryCapsule === 'boolean',
60
+ `Extension bundle ${bundle.id} recoveryCapsule must be a boolean when present.`,
61
+ );
58
62
 
59
63
  const localMemberIds = new Set();
60
64
  for (const memberId of bundle.members) {
@@ -74,7 +78,12 @@ export function validateExtensionBundleConfigurations(extensionBundles, extensio
74
78
  localMemberIds.add(memberId);
75
79
  bundledMemberIds.add(memberId);
76
80
  }
77
- return {id: bundle.id, members: [...bundle.members], name: bundle.name};
81
+ return {
82
+ id: bundle.id,
83
+ members: [...bundle.members],
84
+ name: bundle.name,
85
+ ...(bundle.recoveryCapsule === undefined ? {} : {recoveryCapsule: bundle.recoveryCapsule}),
86
+ };
78
87
  });
79
88
  }
80
89
 
@@ -473,6 +482,9 @@ ${loaders}
473
482
  Scratch.extensions.register(new StaticExtensionBundle());
474
483
  })(Scratch);
475
484
  `;
485
+ if (bundle.recoveryCapsule !== true) {
486
+ return Buffer.from(`${header}\n${runtime}`);
487
+ }
476
488
  const capsule = Buffer.from(
477
489
  JSON.stringify(
478
490
  recoveryCapsule(