@kubohiroya/sb3-toolchain 0.1.1 → 0.3.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.
@@ -0,0 +1,446 @@
1
+ # Static bundles for embedded extensions
2
+
3
+ When a newly opened SB3 contains several unsandboxed extensions, TurboWarp asks for permission to
4
+ run each extension. A static bundle keeps the individual extensions in the expanded source but
5
+ transforms only the generated SB3 into one composite extension, reducing the permission unit to
6
+ one extension.
7
+
8
+ ## Overview
9
+
10
+ ```mermaid
11
+ flowchart LR
12
+ subgraph Source["Expanded source (authoritative)"]
13
+ Project["project.source.json<br/>original opcodes"]
14
+ Alpha["extensions/alpha.js"]
15
+ Beta["extensions/beta.js"]
16
+ end
17
+
18
+ Build["sb3-toolchain build"]
19
+
20
+ subgraph Output["Generated bundled SB3"]
21
+ BundledProject["project.json<br/>namespaced opcodes"]
22
+ Composite["one composite extension<br/>one register() call"]
23
+ Capsule["recovery capsule<br/>original extension data"]
24
+ end
25
+
26
+ TurboWarp["TurboWarp Editor<br/>one permission prompt"]
27
+
28
+ Project --> Build
29
+ Alpha --> Build
30
+ Beta --> Build
31
+ Build --> BundledProject
32
+ Build --> Composite
33
+ Build --> Capsule
34
+ BundledProject --> TurboWarp
35
+ Composite --> TurboWarp
36
+ ```
37
+
38
+ The expanded source always retains the individual extensions. Bundling changes only the generated
39
+ SB3, and the recovery capsule makes that generated artifact reversible when its safety conditions
40
+ remain satisfied.
41
+
42
+ ## What problem it solves
43
+
44
+ TurboWarp grants unsandboxed execution permission per loaded custom extension. A project with three
45
+ embedded extensions therefore presents three prompts even when all three are maintained and shipped
46
+ as one project. The bundle changes the loading boundary, not the security decision itself.
47
+
48
+ ```mermaid
49
+ flowchart LR
50
+ subgraph Before["Without a bundle"]
51
+ BeforeSB3["SB3"] --> PromptA["Allow extension A?"]
52
+ PromptA --> PromptB["Allow extension B?"]
53
+ PromptB --> PromptC["Allow extension C?"]
54
+ PromptC --> RunBefore["Run project"]
55
+ end
56
+
57
+ subgraph After["With a static bundle"]
58
+ AfterSB3["SB3"] --> BundlePrompt["Allow project bundle?"]
59
+ BundlePrompt --> Members["Extension A + B + C"]
60
+ Members --> RunAfter["Run project"]
61
+ end
62
+ ```
63
+
64
+ The user still reviews and authorizes unsandboxed JavaScript. The difference is that the generated
65
+ SB3 exposes one composite extension ID and one embedded extension URL, so TurboWarp has one custom
66
+ extension to authorize and load.
67
+
68
+ ### What it is and what it is not
69
+
70
+ | This feature does | This feature does not |
71
+ | ----------------------------------------------------------------- | ------------------------------------------------------------ |
72
+ | Create one composite runtime extension from several members | Disable or bypass TurboWarp's permission prompt |
73
+ | Rewrite generated project references to collision-free namespaces | Rewrite the authoritative source project in place |
74
+ | Preserve and delegate each member's original implementation | Flatten all member classes into one manually merged class |
75
+ | Embed recovery data for direct SB3 unbundling | Guarantee compatibility for arbitrary dynamic extension code |
76
+ | Reject transformations that cannot be classified safely | Execute extension JavaScript during the build |
77
+
78
+ ## Internal architecture
79
+
80
+ Bundling has separate build-time and runtime layers. Build time validates and rewrites data without
81
+ executing extension JavaScript. Runtime uses a generated wrapper to capture each member registration,
82
+ combine its metadata, and delegate calls.
83
+
84
+ ```mermaid
85
+ flowchart TB
86
+ subgraph BuildTime["Build time: Node.js toolchain"]
87
+ Config["extensionBundles configuration"]
88
+ Sources["Individual member JavaScript"]
89
+ SourceProject["Original project.source.json"]
90
+ Validator["Static contract validator"]
91
+ Generator["Bundle source generator"]
92
+ Rewriter["Project reference rewriter"]
93
+ BundleJS["Generated composite JavaScript"]
94
+ BundledProject["Generated project.json"]
95
+ Archive["Deterministic SB3 archive"]
96
+
97
+ Config --> Validator
98
+ Sources --> Validator
99
+ Validator --> Generator
100
+ SourceProject --> Rewriter
101
+ Config --> Rewriter
102
+ Generator --> BundleJS
103
+ Rewriter --> BundledProject
104
+ BundleJS --> Archive
105
+ BundledProject --> Archive
106
+ end
107
+
108
+ subgraph Runtime["Runtime: TurboWarp"]
109
+ Manager["Extension manager"]
110
+ Wrapper["Generated bundle wrapper"]
111
+ Captured["Captured member instances"]
112
+ Composite["StaticExtensionBundle"]
113
+ Palette["One palette category"]
114
+ VM["Scratch VM execution"]
115
+
116
+ Manager -->|"load one data URL"| Wrapper
117
+ Wrapper -->|"execute members with Scratch proxy"| Captured
118
+ Captured -->|"compose getInfo() and delegates"| Composite
119
+ Composite -->|"register once"| Manager
120
+ Manager --> Palette
121
+ VM -->|"namespaced opcode"| Composite
122
+ Composite -->|"delegate"| Captured
123
+ end
124
+
125
+ Archive --> Manager
126
+ ```
127
+
128
+ ### Anatomy of the generated JavaScript
129
+
130
+ The generated data URL is a self-contained classic extension script with these layers:
131
+
132
+ ```text
133
+ projectbundle.js
134
+ ├── human-readable bundle header
135
+ │ └── member name, ID, author, description, and license
136
+ ├── runtime adapter
137
+ │ ├── Scratch proxy for each member
138
+ │ ├── synchronous register() capture
139
+ │ ├── opcode, menu, custom-field, and hat namespaces
140
+ │ └── global and target storage aliases
141
+ ├── original member source A
142
+ ├── original member source B
143
+ ├── StaticExtensionBundle
144
+ │ ├── combined getInfo()
145
+ │ ├── generated palette headings and separators
146
+ │ └── handlers that delegate to captured member instances
147
+ ├── one real Scratch.extensions.register() call
148
+ └── SB3-Toolchain-Reversible-Bundle-v1 recovery capsule
149
+ ```
150
+
151
+ The original scripts still execute their normal initialization code at runtime. Their calls to
152
+ `Scratch.extensions.register()` are intercepted by a member-specific Scratch proxy instead of being
153
+ sent to TurboWarp. After every member registers exactly once, the wrapper registers the composite
154
+ extension with the real API.
155
+
156
+ ### Runtime call flow
157
+
158
+ ```mermaid
159
+ sequenceDiagram
160
+ participant VM as TurboWarp VM
161
+ participant W as Bundle wrapper
162
+ participant A as Member alpha
163
+ participant B as Member beta
164
+ participant C as Composite extension
165
+
166
+ VM->>W: Load projectbundle data URL
167
+ W->>A: Execute with proxied Scratch
168
+ A-->>W: register(alpha instance) captured
169
+ W->>B: Execute with proxied Scratch
170
+ B-->>W: register(beta instance) captured
171
+ W->>C: Construct combined getInfo() and delegates
172
+ W->>VM: register(composite) once
173
+
174
+ VM->>C: Call alpha__doSomething(args, util)
175
+ C->>A: Call original doSomething(args, util)
176
+ A-->>C: Result
177
+ C-->>VM: Result
178
+
179
+ A->>W: startHats("alpha_whenReady")
180
+ W->>VM: startHats("projectbundle_alpha__whenReady")
181
+ ```
182
+
183
+ ### Data transformations
184
+
185
+ | Concern | Before bundling | Generated bundled SB3 |
186
+ | --------------------------- | ----------------------------------------- | --------------------------------------------- |
187
+ | Loaded extension IDs | `alpha`, `beta` | `projectbundle` |
188
+ | Embedded data URLs | One per member | One composite data URL |
189
+ | Member `getInfo()` opcode | `doSomething` | `alpha__doSomething` |
190
+ | Stored project opcode | `alpha_doSomething` | `projectbundle_alpha__doSomething` |
191
+ | Menu and custom-field names | Member-local names | `memberId__` namespace |
192
+ | `startHats()` opcode | `alpha_whenReady` | `projectbundle_alpha__whenReady` |
193
+ | Extension storage | `storage.alpha`, `storage.beta` | `storage.projectbundle.components.alpha/beta` |
194
+ | Block IDs and graph links | Original IDs and `next`/`parent`/`inputs` | Unchanged |
195
+
196
+ This split is why existing scripts continue to call their original methods while the saved project
197
+ uses the composite extension ID expected by TurboWarp.
198
+
199
+ ## Compatibility and reversibility
200
+
201
+ Bundle configuration is added only to `embedded-extensions.json`. The following authoritative
202
+ sources are not modified:
203
+
204
+ - Original JavaScript in `extensions/<extensionId>.js`
205
+ - Individual extension entries and `source` provenance in `embedded-extensions.json`
206
+ - Original extension IDs, block and monitor opcodes, and extension storage in `project.source.json`
207
+
208
+ `check` and `extensions status|sync|update` continue to validate and update individual extensions.
209
+ Only `build` transforms the in-memory `project.json` and embedded JavaScript into their bundled
210
+ representation. There is no mode that deletes the original files.
211
+
212
+ An extension that cannot be transformed safely is rejected instead of being bundled with changed
213
+ behavior. The current static-bundle contract requires all of the following:
214
+
215
+ - Every member has Extension Gallery-style `Name`, `ID`, `Description`, `By`, and `License` headers
216
+ - The header ID, manifest ID, and runtime `getInfo().id` are identical
217
+ - Every member is a classic script that calls `Scratch.extensions.register` exactly once and synchronously
218
+ - No member uses XML blocks
219
+ - No unclassified opcode references remain outside blocks, monitors, or dynamic block metadata
220
+
221
+ The bundle namespaces ordinary commands, reporters, booleans, events, buttons, labels, static and
222
+ dynamic menus, custom fields, and global and target extension storage. Calls from child extensions
223
+ to `runtime.startHats` are also translated to bundled opcodes.
224
+
225
+ The bundle preserves the `members` order from the manifest and the block-definition order within
226
+ each member's `getInfo().blocks`. In the TurboWarp Editor palette, each group begins with a decorated
227
+ LABEL heading in this form:
228
+
229
+ ```text
230
+ ◆ Bundled extension: <name> [<memberId>] ◆
231
+ ```
232
+
233
+ Two consecutive `---` separators divide member groups. A generated LABEL also carries the following
234
+ machine-readable metadata:
235
+
236
+ ```js
237
+ {
238
+ sb3Toolchain: {
239
+ kind: 'bundle-member-heading',
240
+ memberId,
241
+ },
242
+ }
243
+ ```
244
+
245
+ LABEL entries and separators originally defined by a member are preserved unchanged and in their
246
+ original positions. The decorated bundle heading and wider double separator therefore remain
247
+ visually distinct from an original heading or ordinary separator. A tool can identify the generated
248
+ heading by its `sb3Toolchain` metadata and treat the two separators immediately before it as the
249
+ bundle group boundary.
250
+
251
+ The resulting palette has this visual hierarchy:
252
+
253
+ ```text
254
+ ┌─ Project Extension Bundle ─────────────────────────────┐
255
+ │ ◆ Bundled extension: Alpha Tools [alpha] ◆ │ ← generated heading
256
+ │ alpha block 1 │
257
+ │ Alpha original heading │ ← original LABEL
258
+ │ │ ← original separator
259
+ │ alpha block 2 │
260
+ │ │
261
+ │ │ ← generated double separator
262
+ │ ◆ Bundled extension: Beta Tools [beta] ◆ │ ← generated heading
263
+ │ beta block 1 │
264
+ └────────────────────────────────────────────────────────┘
265
+ ```
266
+
267
+ ## Configure a bundle
268
+
269
+ Start with a dry run to validate the selected members, header metadata, collisions, and opcode
270
+ references.
271
+
272
+ ```bash
273
+ sb3-toolchain extensions bundle app \
274
+ --id projectbundle \
275
+ --name "Project Extension Bundle" \
276
+ extensionone extensiontwo
277
+ ```
278
+
279
+ If member IDs are omitted, all embedded extensions not already assigned to another bundle are
280
+ selected. A bundle requires at least two members. Review the result before applying it.
281
+
282
+ ```bash
283
+ sb3-toolchain extensions bundle app \
284
+ --id projectbundle \
285
+ --name "Project Extension Bundle" \
286
+ extensionone extensiontwo \
287
+ --yes
288
+ sb3-toolchain check app
289
+ sb3-toolchain build app --output dist/project.sb3
290
+ ```
291
+
292
+ Member opcodes are transformed as follows in the generated SB3:
293
+
294
+ ```text
295
+ Original extension getInfo() opcode: doSomething
296
+ Bundle getInfo() opcode: extensionone__doSomething
297
+ Original project.json opcode: extensionone_doSomething
298
+ Bundled project.json opcode: projectbundle_extensionone__doSomething
299
+ ```
300
+
301
+ The bundle adds `memberId + "__"` to each original opcode, so identical opcodes from different
302
+ members cannot collide. Member IDs are restricted to `[a-z0-9]+`, making the delimiter unambiguous.
303
+ Loading the bundle is rejected if transformed opcodes still collide within the same member.
304
+
305
+ Only `projectbundle` appears in `extensions` and `extensionURLs`, and the generated JavaScript calls
306
+ `Scratch.extensions.register` once. The initial comments in that JavaScript list every member's
307
+ name, ID, author, description, and license so the user can inspect them before granting permission.
308
+
309
+ The end of the JavaScript contains an `SB3-Toolchain-Reversible-Bundle-v1` recovery capsule. The
310
+ capsule records each original member data URL, member order, and the original `extensions` and
311
+ `extensionURLs` order.
312
+
313
+ ## Restore from expanded source
314
+
315
+ Choose the restoration path based on which artifact is available:
316
+
317
+ ```mermaid
318
+ flowchart TD
319
+ Start{"What do you have?"}
320
+ Source["Expanded source directory"]
321
+ SB3["Bundled SB3 only"]
322
+ SourceCommand["extensions unbundle SOURCE_DIR"]
323
+ ArchiveCommand["extensions unbundle INPUT.sb3<br/>--output OUTPUT.sb3"]
324
+ Rebuild["Rebuild from preserved<br/>project.source.json and member JS"]
325
+ Recover["Validate recovery capsule<br/>and reverse project transformations"]
326
+ Restored["SB3 with individual extensions"]
327
+
328
+ Start -->|"authoritative source"| Source
329
+ Start -->|"distribution artifact"| SB3
330
+ Source --> SourceCommand --> Rebuild --> Restored
331
+ SB3 --> ArchiveCommand --> Recover --> Restored
332
+ ```
333
+
334
+ First inspect the unbundle plan with a dry run, then pass `--yes` to remove the bundle configuration.
335
+
336
+ ```bash
337
+ sb3-toolchain extensions unbundle app projectbundle
338
+ sb3-toolchain extensions unbundle app projectbundle --yes
339
+ sb3-toolchain check app
340
+ sb3-toolchain build app --output dist/project.sb3 --yes
341
+ ```
342
+
343
+ Because the original JavaScript and project representation are preserved, the next build restores
344
+ the individual IDs and data URLs and regenerates block, dynamic block metadata, and monitor opcodes
345
+ with their original values. This form of unbundle does not attempt to reverse-engineer a distribution
346
+ SB3. It regenerates the project from the saved `project.source.json` and individual JavaScript, so no
347
+ information is lost through an inferred opcode reversal. If `extensions update` ran while the bundle
348
+ was configured, the project is restored using the updated individual JavaScript.
349
+
350
+ Treat the expanded source as authoritative. Do not re-import a generated bundled SB3 into that same
351
+ authoritative source. Importing it into a new directory expands the distribution composite extension
352
+ as one ordinary extension and cannot recover the individual provenance. The normal Git-difference
353
+ protection and replacement confirmation still apply if an existing authoritative source is selected
354
+ accidentally.
355
+
356
+ ## Restore a bundled SB3 directly
357
+
358
+ A bundled SB3 containing a recovery capsule can be unbundled without the expanded source. The
359
+ command is a dry run unless `--yes` is supplied.
360
+
361
+ ```bash
362
+ sb3-toolchain extensions unbundle \
363
+ dist/project.sb3 projectbundle \
364
+ --output dist/project.unbundled.sb3
365
+ sb3-toolchain extensions unbundle \
366
+ dist/project.sb3 projectbundle \
367
+ --output dist/project.unbundled.sb3 \
368
+ --yes
369
+ ```
370
+
371
+ Direct unbundling restores all of the following:
372
+
373
+ - Bundle opcodes to `memberId_originalOpcode`, while leaving block IDs, `next`, `parent`, and `inputs` unchanged
374
+ - Opcodes in ordinary blocks, dynamic block metadata, and monitors
375
+ - The bundle storage `components` as storage keyed by the original member IDs
376
+ - Individual member data URLs and the original order of `extensions` and `extensionURLs`
377
+ - Asset entries and their byte contents
378
+
379
+ Blocks may be added, deleted, or moved in TurboWarp after bundling. An added block can still be
380
+ restored when its opcode has the `bundleId_memberId__originalOpcode` form. An SB3 containing several
381
+ bundles can be unbundled one bundle at a time in any order when every bundle has a valid recovery
382
+ capsule and their member sets do not overlap.
383
+
384
+ ### Conditions that make direct unbundling impossible
385
+
386
+ ```mermaid
387
+ flowchart TD
388
+ Input["Bundled SB3"]
389
+ Capsule{"Valid recovery capsule?"}
390
+ Order{"Extension ID set and<br/>order still match?"}
391
+ Mapping{"Every bundle opcode maps<br/>to exactly one member?"}
392
+ Storage{"Storage uses reversible<br/>format 1 without collisions?"}
393
+ Write["Write unbundled SB3"]
394
+ Refuse["Refuse safely<br/>leave output unchanged"]
395
+
396
+ Input --> Capsule
397
+ Capsule -->|"yes"| Order
398
+ Capsule -->|"no"| Refuse
399
+ Order -->|"yes"| Mapping
400
+ Order -->|"no"| Refuse
401
+ Mapping -->|"yes"| Storage
402
+ Mapping -->|"no"| Refuse
403
+ Storage -->|"yes"| Write
404
+ Storage -->|"no"| Refuse
405
+ ```
406
+
407
+ The tool refuses the operation without modifying the output instead of guessing when any of the
408
+ following conditions apply:
409
+
410
+ - The target data URL has no `SB3-Toolchain-Reversible-Bundle-v1` capsule because the bundle was
411
+ produced before recovery capsules were introduced, by another tool, or by hand
412
+ - The bundle data URL or capsule was removed, corrupted, or duplicated; its format version is not
413
+ supported; or its bundle ID, member ID, and original JavaScript header ID do not agree
414
+ - The ID set or order in `project.extensions` or `extensionURLs` changed after bundling. For example,
415
+ adding or removing another extension makes the exact insertion positions of the original members
416
+ unsafe to infer
417
+ - An opcode beginning with `bundleId_` cannot be assigned to a member's `memberId__` namespace, or
418
+ an unclassified bundle opcode reference remains outside ordinary blocks, dynamic block metadata,
419
+ and monitors
420
+ - Bundle storage is not `{formatVersion: 1, components: {...}}`, contains an unknown member or an
421
+ additional bundle-level field, or collides with storage already using a restored member ID
422
+ - Active reversible bundles contain overlapping members
423
+ - The ZIP is empty, `project.json` is missing or invalid, an entry name is unsafe, or entry order
424
+ cannot be preserved safely
425
+
426
+ If the expanded source is still available, these conditions do not prevent the source-based
427
+ `extensions unbundle SOURCE_DIR` workflow from removing the bundle configuration and rebuilding the
428
+ project. An older generated SB3 without a recovery capsule cannot be reversed directly from that SB3
429
+ alone.
430
+
431
+ Direct unbundling preserves asset bytes but recompresses the ZIP deterministically. It does not
432
+ preserve byte-for-byte identity of input ZIP metadata, entry timestamps, or archive comments.
433
+
434
+ ## Verification
435
+
436
+ Static validation cannot prove compatibility with browser APIs, cameras, the renderer, or implicit
437
+ dependencies between extensions. Run the same project-level automated tests before and after
438
+ bundling, then open the generated SB3 in a fresh TurboWarp session and verify all of the following:
439
+
440
+ - The unsandboxed execution prompt appears only once
441
+ - Green flag behavior and block, reporter, hat, monitor, and menu results are unchanged
442
+ - Permission paths used by the project, such as camera, network, file picker, and renderer access, work
443
+ - An SB3 saved again by TurboWarp retains extension storage and still works after reloading
444
+
445
+ Exclude a member from the bundle and keep it as an individual extension when its compatibility
446
+ cannot be verified.
@@ -1,59 +1,70 @@
1
- # 埋め込み拡張IDの移行
1
+ # Migrating embedded extension IDs
2
2
 
3
- TurboWarpで読み込み済みの拡張IDは、project内のopcodeやmonitorにも保存されます。
4
- `extensions migrate-id`はJSON全体の文字列置換を行わず、SB3 source format v1で意味が
5
- 確定している参照だけを変更します。
3
+ TurboWarp stores the IDs of loaded extensions in project opcodes and monitors. `extensions migrate-id`
4
+ does not perform a global string replacement. It changes only references whose meaning is defined by
5
+ SB3 source format v1.
6
6
 
7
- ## dry-runと適用
7
+ ## Dry run and apply
8
8
 
9
- 単独の移行コマンドは既定でdry-runです。
9
+ The standalone migration command is a dry run by default.
10
10
 
11
11
  ```bash
12
12
  sb3-toolchain extensions migrate-id app --from twOld --to newext
13
13
  ```
14
14
 
15
- 出力される分類済み変更件数と`Unclassified`参照を確認し、新IDを宣言するJavaScript成果物を
16
- `extensions/twOld.js`へ用意してから明示的に適用します。
15
+ Review the classified change counts and `Unclassified` references. Before applying the migration,
16
+ place a JavaScript artifact that declares the new ID at `extensions/twOld.js`.
17
17
 
18
18
  ```bash
19
19
  sb3-toolchain extensions migrate-id app --from twOld --to newext --yes
20
20
  ```
21
21
 
22
- 新IDはTurboWarp公式形式の`[a-z0-9]+`でなければなりません。既存のmanifest、
23
- `extensionURLs`、または`project.extensions`に新IDが存在する場合はcollisionとして
24
- 拒否します。
22
+ The new ID must use TurboWarp's official `[a-z0-9]+` format. The migration is rejected as a collision
23
+ if the new ID already exists in the manifest, `extensionURLs`, or `project.extensions`.
25
24
 
26
- ## 分類して変更する参照
25
+ ## Classified references
27
26
 
28
- - `project.source.json`の`extensions[]`にある完全一致ID
29
- - `extensionURLs`の完全一致keyと埋め込み拡張value
30
- - `targets[*].blocks[*].opcode`の`<oldId>_`完全prefix
31
- - menu blockのopcode(通常のblockと同じschema)
32
- - `monitors[*].opcode`の`<oldId>_`完全prefix
33
- - `embedded-extensions.json`の`id`と`path`
34
- - `extensions/<oldId>.js`から`extensions/<newId>.js`へのファイル名変更
27
+ The tool changes the following references:
35
28
 
36
- 変数名、list名、blockのliteral、metadata、別拡張のopcodeなどに旧IDを含む文字列は
37
- 変更しません。これらはJSON Pointer付きの未分類参照としてdry-run結果へ出すため、人が
38
- 意味を確認できます。
29
+ - Exact IDs in `project.source.json` `extensions[]`
30
+ - Exact `extensionURLs` keys and embedded-extension values
31
+ - Exact `<oldId>_` prefixes in `targets[*].blocks[*].opcode`
32
+ - Menu block opcodes, which use the ordinary block schema
33
+ - Exact `<oldId>_` prefixes in `monitors[*].opcode`
34
+ - `id` and `path` in `embedded-extensions.json`
35
+ - The filename from `extensions/<oldId>.js` to `extensions/<newId>.js`
39
36
 
40
- ## GitHub管理対象
37
+ Strings containing the old ID in variable names, list names, block literals, metadata, or another
38
+ extension's opcode are not changed. They appear in the dry-run output as unclassified references
39
+ with JSON Pointers so that a person can determine their meaning.
41
40
 
42
- 管理対象拡張では、上流リポジトリが新IDを宣言する成果物を公開したあと、更新と移行を
43
- 一体で実行する方法を推奨します。
41
+ ## GitHub-managed extensions
42
+
43
+ For a managed extension, the recommended workflow combines the update and migration after the
44
+ upstream repository publishes an artifact declaring the new ID.
44
45
 
45
46
  ```bash
46
47
  sb3-toolchain extensions update app twOld \
47
48
  --migrate-id newext \
48
- --artifact dist/newext.js
49
+ --artifact dist/newext.js \
50
+ --api-manifest-artifact dist/newext.manifest.json
49
51
  ```
50
52
 
51
- `--artifact`は上流の成果物パスも変わる場合だけ指定します。ツールは追跡refを固定commitへ
52
- 解決し、そのcommitから新成果物を取得します。`// ID: newext`を宣言しない成果物、
53
- collision、不正な新IDは、ローカルファイルを変更する前に拒否します。
53
+ Specify `--artifact` only when the upstream JavaScript artifact path changed. Specify
54
+ `--api-manifest-artifact` only when an opt-in manifest artifact path also changed. The tool resolves
55
+ the tracked ref to an immutable commit and downloads the new artifacts from that commit. It rejects
56
+ an artifact that does not declare `// ID: newext`, a collision, or an invalid new ID before changing
57
+ local files.
58
+
59
+ If the managed extension has `source.apiManifest`, the tool downloads the candidate manifest from
60
+ the same commit, normalizes only the explicit old and new top-level IDs, and applies the ordinary API
61
+ compatibility policy to every remaining field. JavaScript, the renamed local manifest, provenance,
62
+ both remote artifact paths when supplied, and both integrity values change in one transaction. See
63
+ [`extension-api-compatibility.md`](extension-api-compatibility.md).
54
64
 
55
- ## 検証とロールバック
65
+ ## Validation and rollback
56
66
 
57
- 適用候補について通常のsource検証と決定的SB3 buildを完了してから、展開ディレクトリを
58
- transactionalに置換します。途中失敗時は元ディレクトリを自動復旧します。マージ後に
59
- 戻す場合は、作品側の移行commitをrevertし、旧ID・旧成果物・旧provenanceを同時に戻します。
67
+ The tool completes normal source validation and a deterministic candidate SB3 build before replacing
68
+ the expanded source directory transactionally. It restores the original directory automatically if
69
+ replacement fails. To roll back after merge, revert the project migration commit so that the old ID,
70
+ artifact, and provenance return together.