@kubohiroya/sb3-toolchain 0.1.1 → 0.2.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.md +54 -96
- package/docs/extension-bundles.md +446 -0
- package/docs/extension-id-migration.md +34 -32
- package/docs/source-format-v1.md +112 -61
- package/docs/workflows.md +235 -0
- package/package.json +1 -1
- package/src/build.js +21 -7
- package/src/cli.js +149 -2
- package/src/constants.js +1 -1
- package/src/extension-bundle-archive.js +422 -0
- package/src/extension-bundle-configuration.js +247 -0
- package/src/extension-bundle.js +640 -0
- package/src/extension-dependencies.js +14 -1
- package/src/index.js +14 -0
- package/src/source.js +33 -7
|
@@ -1,46 +1,47 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Migrating embedded extension IDs
|
|
2
2
|
|
|
3
|
-
TurboWarp
|
|
4
|
-
|
|
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
|
-
##
|
|
7
|
+
## Dry run and apply
|
|
8
8
|
|
|
9
|
-
|
|
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
|
-
|
|
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
|
-
|
|
23
|
-
`extensionURLs
|
|
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
|
-
|
|
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
|
-
|
|
37
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 \
|
|
@@ -48,12 +49,13 @@ sb3-toolchain extensions update app twOld \
|
|
|
48
49
|
--artifact dist/newext.js
|
|
49
50
|
```
|
|
50
51
|
|
|
51
|
-
`--artifact
|
|
52
|
-
|
|
53
|
-
collision
|
|
52
|
+
Specify `--artifact` only when the upstream artifact path also changed. The tool resolves the tracked
|
|
53
|
+
ref to an immutable commit and downloads the new artifact from that commit. It rejects an artifact
|
|
54
|
+
that does not declare `// ID: newext`, a collision, or an invalid new ID before changing local files.
|
|
54
55
|
|
|
55
|
-
##
|
|
56
|
+
## Validation and rollback
|
|
56
57
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
58
|
+
The tool completes normal source validation and a deterministic candidate SB3 build before replacing
|
|
59
|
+
the expanded source directory transactionally. It restores the original directory automatically if
|
|
60
|
+
replacement fails. To roll back after merge, revert the project migration commit so that the old ID,
|
|
61
|
+
artifact, and provenance return together.
|
package/docs/source-format-v1.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# SB3
|
|
1
|
+
# SB3 expanded source format v1
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## Layout
|
|
4
4
|
|
|
5
5
|
```text
|
|
6
6
|
SOURCE_DIR/
|
|
@@ -13,7 +13,8 @@ SOURCE_DIR/
|
|
|
13
13
|
└── <extensionId>.js
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
`sb3-source.json
|
|
16
|
+
`sb3-source.json` records the format version, paths to each component, and the ZIP entry order of the
|
|
17
|
+
original SB3.
|
|
17
18
|
|
|
18
19
|
```json
|
|
19
20
|
{
|
|
@@ -27,21 +28,21 @@ SOURCE_DIR/
|
|
|
27
28
|
|
|
28
29
|
## `project.source.json`
|
|
29
30
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
31
|
+
This file is the original SB3 `project.json` formatted as two-space-indented JSON. Array and object
|
|
32
|
+
order are preserved as meaningful input. A TurboWarp extension that was embedded as a data URL is
|
|
33
|
+
replaced by this reference:
|
|
33
34
|
|
|
34
35
|
```text
|
|
35
36
|
embedded-extension:extensions/<extensionId>.js
|
|
36
37
|
```
|
|
37
38
|
|
|
38
|
-
|
|
39
|
-
|
|
39
|
+
During a build, the media type, parameters, and encoding from `embedded-extensions.json` are used to
|
|
40
|
+
reconstruct the data URL.
|
|
40
41
|
|
|
41
42
|
## `embedded-extensions.json`
|
|
42
43
|
|
|
43
|
-
|
|
44
|
-
|
|
44
|
+
This file records embedded extension data URL information and extraction paths. Optional `source`
|
|
45
|
+
metadata can be added for an extension managed from GitHub.
|
|
45
46
|
|
|
46
47
|
```json
|
|
47
48
|
{
|
|
@@ -66,54 +67,104 @@ embedded-extension:extensions/<extensionId>.js
|
|
|
66
67
|
}
|
|
67
68
|
```
|
|
68
69
|
|
|
69
|
-
- `repository`: `<owner>/<repository
|
|
70
|
-
- `ref`:
|
|
71
|
-
- `resolvedCommit`:
|
|
72
|
-
- `artifact`:
|
|
73
|
-
- `integrity`:
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
-
|
|
78
|
-
-
|
|
79
|
-
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
`
|
|
87
|
-
`
|
|
88
|
-
`integrity
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
`
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
70
|
+
- `repository`: GitHub repository in `<owner>/<repository>` form
|
|
71
|
+
- `ref`: branch, tag, or commit to track for update candidates
|
|
72
|
+
- `resolvedCommit`: lowercase 40-character commit SHA used to obtain the current file
|
|
73
|
+
- `artifact`: JavaScript artifact path relative to the repository root
|
|
74
|
+
- `integrity`: SRI-form SHA-256 of the current file
|
|
75
|
+
|
|
76
|
+
Validation and builds verify managed extensions without accessing the network:
|
|
77
|
+
|
|
78
|
+
- The actual file SHA-256 matches `integrity`
|
|
79
|
+
- The file's `// ID: <extensionId>` header matches `id`
|
|
80
|
+
- The repository, ref, commit, and artifact path use safe forms
|
|
81
|
+
|
|
82
|
+
Re-importing an SB3 into an existing expanded source directory preserves `source` metadata for the
|
|
83
|
+
same ID and path. If the imported file does not match the recorded hash or ID, the import is rejected
|
|
84
|
+
without changing the existing output. A new import cannot infer provenance, so it does not create
|
|
85
|
+
`source` automatically.
|
|
86
|
+
|
|
87
|
+
`extensions sync` downloads `artifact` using the immutable `resolvedCommit` and restores the local
|
|
88
|
+
file only when the downloaded ID and hash match the existing metadata. `extensions update` resolves
|
|
89
|
+
`ref` through the GitHub API and updates `resolvedCommit` and `integrity` to match the artifact from
|
|
90
|
+
that commit. The expanded source is not changed until every selected entry has been downloaded and
|
|
91
|
+
validated successfully.
|
|
92
|
+
|
|
93
|
+
An extension ID migration changes the manifest `id` and `path`, known references in
|
|
94
|
+
`project.source.json`, and `extensions/<id>.js` in one transaction. When a managed extension is
|
|
95
|
+
migrated as part of `extensions update`, `artifact` when explicitly supplied, `resolvedCommit`, and
|
|
96
|
+
`integrity` are also updated for the new artifact.
|
|
97
|
+
|
|
98
|
+
### `extensionBundles`
|
|
99
|
+
|
|
100
|
+
Add the optional `extensionBundles` array to make multiple individual extensions one permission unit
|
|
101
|
+
only in the generated SB3.
|
|
102
|
+
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"formatVersion": 1,
|
|
106
|
+
"extensions": [
|
|
107
|
+
{
|
|
108
|
+
"id": "extensionone",
|
|
109
|
+
"path": "extensions/extensionone.js",
|
|
110
|
+
"mediaType": "text/javascript",
|
|
111
|
+
"parameters": [],
|
|
112
|
+
"encoding": "base64"
|
|
113
|
+
},
|
|
114
|
+
{
|
|
115
|
+
"id": "extensiontwo",
|
|
116
|
+
"path": "extensions/extensiontwo.js",
|
|
117
|
+
"mediaType": "text/javascript",
|
|
118
|
+
"parameters": [],
|
|
119
|
+
"encoding": "base64"
|
|
120
|
+
}
|
|
121
|
+
],
|
|
122
|
+
"extensionBundles": [
|
|
123
|
+
{
|
|
124
|
+
"id": "projectbundle",
|
|
125
|
+
"name": "Project Extension Bundle",
|
|
126
|
+
"members": ["extensionone", "extensiontwo"]
|
|
127
|
+
}
|
|
128
|
+
]
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
- `id`: composite extension ID in TurboWarp's `[a-z0-9]+` form that does not collide with an individual extension
|
|
133
|
+
- `name`: single-line name displayed in the permission prompt and extension category
|
|
134
|
+
- `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
|
|
135
|
+
|
|
136
|
+
A member cannot belong to more than one bundle. Individual entries, individual JavaScript, `source`,
|
|
137
|
+
and `project.source.json` remain authoritative. `build` adds `memberId + "__"` to each original opcode
|
|
138
|
+
and changes only the output `project.json` opcodes, `extensions`, `extensionURLs`, and extension storage
|
|
139
|
+
to the bundle ID. It embeds one bundle JavaScript data URL.
|
|
140
|
+
|
|
141
|
+
The end of the bundle JavaScript contains a format 1 recovery capsule with the original individual
|
|
142
|
+
data URLs and extension order. Removing the configuration or running `extensions unbundle` against a
|
|
143
|
+
generated SB3 containing that capsule restores the ordinary output. See
|
|
144
|
+
[`extension-bundles.md`](extension-bundles.md) for the compatibility contract and restoration steps.
|
|
145
|
+
|
|
146
|
+
## Assets
|
|
147
|
+
|
|
148
|
+
`assets/` contains costumes and sounds referenced by `project.source.json`. Each filename is
|
|
149
|
+
`<assetId>.<dataFormat>`, and `assetId` must match the MD5 of its contents. An unreferenced, missing,
|
|
150
|
+
or extra file is a validation error.
|
|
151
|
+
|
|
152
|
+
## Deterministic output
|
|
153
|
+
|
|
154
|
+
- ZIP entries follow `archiveEntries`
|
|
155
|
+
- ZIP timestamps are fixed at 1980-01-01 00:00:00
|
|
156
|
+
- Compression level is fixed at 6
|
|
157
|
+
- `project.json` is stored as minimal JSON with a trailing newline
|
|
158
|
+
- The same source format version, input files, and tool version produce the same byte sequence
|
|
159
|
+
|
|
160
|
+
## Safety
|
|
161
|
+
|
|
162
|
+
- Reject ZIP entries containing absolute paths, `\`, empty components, `.`, or `..`
|
|
163
|
+
- Reject symbolic links and special files as source input
|
|
164
|
+
- Reject a filesystem root, Git repository root, its ancestor, or `.git/` as an import destination
|
|
165
|
+
- Never overwrite an unrecognized existing directory
|
|
166
|
+
- Never discard Git-managed changes without the explicit two-stage override
|
|
167
|
+
- Never overwrite automatically when an interrupted replacement rollback area is present
|
|
168
|
+
- Verify managed extensions offline against their commit, SHA-256, and extension ID
|
|
169
|
+
- Preserve individual JavaScript and provenance during bundling and reject contracts whose compatibility cannot be established
|
|
170
|
+
- Fetch from GitHub only over HTTPS with redirects rejected and a size limit, and never execute downloaded JavaScript
|
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
# SB3 source-management workflows
|
|
2
|
+
|
|
3
|
+
This document describes the common workflow for managing a Scratch 3 or TurboWarp SB3 as expanded
|
|
4
|
+
source in Git and rebuilding a validated SB3. Each project repository should define its own editing,
|
|
5
|
+
testing, and distribution procedures.
|
|
6
|
+
|
|
7
|
+
See [`source-format-v1.md`](source-format-v1.md) for the expanded directory layout and file formats.
|
|
8
|
+
|
|
9
|
+
## Principles
|
|
10
|
+
|
|
11
|
+
- Treat the expanded directory in Git as the source of truth and generated SB3 files as build artifacts
|
|
12
|
+
- Import an SB3 edited in the TurboWarp Editor only after reviewing its differences
|
|
13
|
+
- Run `check` before committing and before distribution
|
|
14
|
+
- Build in CI and release workflows from a pinned toolchain version and committed expanded source
|
|
15
|
+
- Reproduce managed embedded extensions from a pinned source commit and SHA-256
|
|
16
|
+
|
|
17
|
+
The examples below use `app/` for the expanded source, `tmp/edited.sb3` for an SB3 saved by the
|
|
18
|
+
editor, and `dist/project.sb3` for generated output. Choose project-specific paths as needed.
|
|
19
|
+
|
|
20
|
+
## Initial import
|
|
21
|
+
|
|
22
|
+
Expand an SB3 saved by TurboWarp into files suitable for Git.
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
sb3-toolchain import tmp/edited.sb3 --output app
|
|
26
|
+
sb3-toolchain check app
|
|
27
|
+
git status --short
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
After import, verify at least the following:
|
|
31
|
+
|
|
32
|
+
- Changes in `project.source.json` correspond to operations performed in the editor
|
|
33
|
+
- Only intended assets were added to or removed from `assets/`
|
|
34
|
+
- `extensions/` and `embedded-extensions.json` contain no unexpected changes
|
|
35
|
+
- `sb3-toolchain check app` succeeds
|
|
36
|
+
|
|
37
|
+
A new import does not infer where embedded JavaScript came from. Add the provenance metadata described
|
|
38
|
+
below when an extension hosted on GitHub should become managed.
|
|
39
|
+
|
|
40
|
+
## Re-import into existing source
|
|
41
|
+
|
|
42
|
+
After editing the project, import the saved SB3 into the existing expanded source directory.
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
git status --short
|
|
46
|
+
sb3-toolchain import tmp/edited.sb3 --output app
|
|
47
|
+
sb3-toolchain check app
|
|
48
|
+
git diff -- app
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The tool asks for replacement confirmation when the existing expanded source differs. In a
|
|
52
|
+
non-interactive environment, `--yes` skips that confirmation but does not discard uncommitted
|
|
53
|
+
Git-managed changes. Specify both options only after reviewing the changes that will be discarded.
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
sb3-toolchain import tmp/edited.sb3 --output app \
|
|
57
|
+
--yes \
|
|
58
|
+
--discard-local-changes
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`--discard-local-changes` is not a recovery mechanism. Commit or otherwise preserve required changes
|
|
62
|
+
before using it. There is no `--force` option.
|
|
63
|
+
|
|
64
|
+
Provenance metadata for a managed extension with the same ID and path is preserved during re-import.
|
|
65
|
+
If the JavaScript in the SB3 differs from the recorded ID or SHA-256, the import is rejected without
|
|
66
|
+
changing the existing output, preventing provenance from becoming inconsistent with the actual file.
|
|
67
|
+
|
|
68
|
+
## Validation and build
|
|
69
|
+
|
|
70
|
+
Use `check` to validate only the expanded source and `build` to generate an SB3.
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
sb3-toolchain check app
|
|
74
|
+
sb3-toolchain build app --output dist/project.sb3
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`check` and `build` do not access the network. They validate asset references, MD5 hashes, the
|
|
78
|
+
expanded format, embedded extension IDs, and SHA-256 hashes using only local inputs.
|
|
79
|
+
|
|
80
|
+
`build` fixes the ZIP entry order, timestamps, and compression settings. The same toolchain version
|
|
81
|
+
and expanded source produce a bit-for-bit identical SB3. An identical existing output is left
|
|
82
|
+
untouched. A differing output requires replacement confirmation or `--yes`.
|
|
83
|
+
|
|
84
|
+
In addition to project-specific tests, open the generated SB3 in TurboWarp and verify startup, primary
|
|
85
|
+
operations, images, sounds, and embedded extension behavior.
|
|
86
|
+
|
|
87
|
+
## Managed embedded extensions
|
|
88
|
+
|
|
89
|
+
The `source` object in `embedded-extensions.json` can record the GitHub repository, tracked ref,
|
|
90
|
+
resolved commit, artifact path, and SHA-256. See [`source-format-v1.md`](source-format-v1.md) for the
|
|
91
|
+
complete schema.
|
|
92
|
+
|
|
93
|
+
The extension commands have the following roles:
|
|
94
|
+
|
|
95
|
+
| Command | Network | Resolve ref | Metadata update | Purpose |
|
|
96
|
+
| ----------------------- | ------- | ----------- | --------------- | ------------------------------------------- |
|
|
97
|
+
| `extensions status` | Yes | Yes | No | Check whether a tracked ref has an update |
|
|
98
|
+
| `extensions sync` | Yes | No | No | Restore files from the pinned commit |
|
|
99
|
+
| `extensions update` | Yes | Yes | Yes | Explicitly update to the latest ref commit |
|
|
100
|
+
| `extensions migrate-id` | No | No | IDs/references | Migrate an extension ID used by the project |
|
|
101
|
+
| `extensions bundle` | No | No | Bundle config | Combine extensions into one permission unit |
|
|
102
|
+
| `extensions unbundle` | No | No | Config or SB3 | Restore output with individual extensions |
|
|
103
|
+
|
|
104
|
+
### Check for updates
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
sb3-toolchain extensions status app
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
`status` does not change local files. Review upstream changes for extensions whose tracked ref differs
|
|
111
|
+
from `resolvedCommit`, then decide whether to update.
|
|
112
|
+
|
|
113
|
+
### Restore from a pinned commit
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
sb3-toolchain extensions sync app
|
|
117
|
+
sb3-toolchain check app
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
`sync` does not resolve a mutable branch or tag. It downloads from the recorded `resolvedCommit` and
|
|
121
|
+
replaces a local file only when the artifact ID and SHA-256 match the recorded metadata.
|
|
122
|
+
|
|
123
|
+
### Update a tracked ref
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
sb3-toolchain extensions update app
|
|
127
|
+
sb3-toolchain extensions update app EXTENSION_ID
|
|
128
|
+
sb3-toolchain check app
|
|
129
|
+
git diff -- app
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Omitting the ID updates all managed extensions as one transaction. If any download or validation
|
|
133
|
+
fails, neither files nor metadata are changed.
|
|
134
|
+
|
|
135
|
+
In an update PR, review `resolvedCommit`, `integrity`, and the JavaScript artifact together, then test
|
|
136
|
+
the extension's primary features in the generated SB3.
|
|
137
|
+
|
|
138
|
+
## Migrate an extension ID
|
|
139
|
+
|
|
140
|
+
An extension ID is stored in opcodes and monitors, so do not change only its filename or manifest by
|
|
141
|
+
hand. Start with a dry run and inspect both classified and unclassified references.
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Prepare JavaScript declaring the new ID, review the result, and then apply it.
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID --yes
|
|
151
|
+
sb3-toolchain check app
|
|
152
|
+
git diff -- app
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
For a GitHub-managed extension, the upstream artifact update and ID migration can be one transaction.
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
sb3-toolchain extensions update app OLD_ID \
|
|
159
|
+
--migrate-id NEW_ID \
|
|
160
|
+
--artifact dist/NEW_ID.js
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Specify `--artifact` only when the upstream artifact path also changed. See
|
|
164
|
+
[`extension-id-migration.md`](extension-id-migration.md) for the affected schema, collision checks,
|
|
165
|
+
unclassified references, and rollback details.
|
|
166
|
+
|
|
167
|
+
## Combine unsandboxed permission into one prompt
|
|
168
|
+
|
|
169
|
+
A project containing several embedded extensions can opt in to a static bundle. Original JavaScript,
|
|
170
|
+
IDs, opcodes, and provenance remain unchanged; only build output is transformed into one composite
|
|
171
|
+
extension.
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
sb3-toolchain extensions bundle app \
|
|
175
|
+
--id projectbundle \
|
|
176
|
+
--name "Project Extension Bundle" \
|
|
177
|
+
extensionone extensiontwo
|
|
178
|
+
sb3-toolchain extensions bundle app \
|
|
179
|
+
--id projectbundle \
|
|
180
|
+
--name "Project Extension Bundle" \
|
|
181
|
+
extensionone extensiontwo \
|
|
182
|
+
--yes
|
|
183
|
+
sb3-toolchain check app
|
|
184
|
+
sb3-toolchain build app --output dist/project.sb3 --yes
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Use project-level automated tests and a real TurboWarp smoke test to verify equivalent behavior before
|
|
188
|
+
and after bundling, a single permission prompt, and successful reload after saving. If there is a
|
|
189
|
+
problem, restore the preserved individual extensions.
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
sb3-toolchain extensions unbundle app projectbundle
|
|
193
|
+
sb3-toolchain extensions unbundle app projectbundle --yes
|
|
194
|
+
sb3-toolchain check app
|
|
195
|
+
sb3-toolchain build app --output dist/project.sb3 --yes
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
An SB3 generated by this version of the toolchain can also be unbundled directly when the expanded
|
|
199
|
+
source is unavailable. The first command is a dry run; output is written only with `--yes`.
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
sb3-toolchain extensions unbundle \
|
|
203
|
+
dist/project.sb3 projectbundle \
|
|
204
|
+
--output dist/project.unbundled.sb3
|
|
205
|
+
sb3-toolchain extensions unbundle \
|
|
206
|
+
dist/project.sb3 projectbundle \
|
|
207
|
+
--output dist/project.unbundled.sb3 \
|
|
208
|
+
--yes
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
See [`extension-bundles.md`](extension-bundles.md) for the compatibility contract, source comments,
|
|
212
|
+
opcode and storage transformations, direct-unbundle limitations, and re-import precautions.
|
|
213
|
+
|
|
214
|
+
## CI and distribution
|
|
215
|
+
|
|
216
|
+
Pin dependency versions and run at least the following in CI:
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
sb3-toolchain check app
|
|
220
|
+
sb3-toolchain build app --output dist/project.sb3 --yes
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Distribute only an SB3 that passed project-level automated tests and manual verification. Do not
|
|
224
|
+
implicitly run `sync` or `update` as part of a release build because that would make network state an
|
|
225
|
+
input. Perform updates as separate, reviewable changes and commit the pinned expanded source first.
|
|
226
|
+
|
|
227
|
+
## Handling failures
|
|
228
|
+
|
|
229
|
+
- If a command refuses replacement, inspect `git status` and the relevant differences before retrying
|
|
230
|
+
- If `.<output-name>.rollback-*` remains, compare it with the current output before deciding what to restore or remove
|
|
231
|
+
- After a partial extension update failure, inspect `git diff` before retrying
|
|
232
|
+
- Roll back a merged change by reverting the project commit so source, artifacts, and provenance return together
|
|
233
|
+
- When replacing a published SB3, follow the project's release policy and preserve history
|
|
234
|
+
|
|
235
|
+
Do not destroy Git history as a recovery shortcut. Keep the cause and affected scope inspectable.
|
package/package.json
CHANGED
package/src/build.js
CHANGED
|
@@ -103,8 +103,13 @@ async function installArchiveTransactionally(archive, outputPath, expectedOutput
|
|
|
103
103
|
}
|
|
104
104
|
}
|
|
105
105
|
|
|
106
|
-
export async function
|
|
107
|
-
|
|
106
|
+
export async function writeSb3Archive({
|
|
107
|
+
archive,
|
|
108
|
+
confirmReplace = undefined,
|
|
109
|
+
outputPath,
|
|
110
|
+
yes = false,
|
|
111
|
+
}) {
|
|
112
|
+
assert(archive instanceof Uint8Array, 'SB3 archive contents are required.');
|
|
108
113
|
assert(typeof outputPath === 'string', 'SB3 output path is required.');
|
|
109
114
|
const resolvedOutputPath = path.resolve(outputPath);
|
|
110
115
|
assert(
|
|
@@ -112,12 +117,10 @@ export async function buildSb3({confirmReplace, outputPath, sourceDirectory, yes
|
|
|
112
117
|
`SB3 output path must use the .sb3 extension: ${resolvedOutputPath}`,
|
|
113
118
|
);
|
|
114
119
|
await assertNoInterruptedRollback(resolvedOutputPath);
|
|
115
|
-
const built = await createDeterministicSb3(sourceDirectory);
|
|
116
120
|
const existingOutput = await inspectOutput(resolvedOutputPath);
|
|
117
121
|
if (existingOutput.exists) {
|
|
118
|
-
if (Buffer.compare(existingOutput.contents, Buffer.from(
|
|
122
|
+
if (Buffer.compare(existingOutput.contents, Buffer.from(archive)) === 0) {
|
|
119
123
|
return {
|
|
120
|
-
...built,
|
|
121
124
|
changed: false,
|
|
122
125
|
outputPath: resolvedOutputPath,
|
|
123
126
|
rollbackCleanupWarning: null,
|
|
@@ -138,14 +141,25 @@ export async function buildSb3({confirmReplace, outputPath, sourceDirectory, yes
|
|
|
138
141
|
|
|
139
142
|
await mkdir(path.dirname(resolvedOutputPath), {recursive: true});
|
|
140
143
|
const rollbackCleanupWarning = await installArchiveTransactionally(
|
|
141
|
-
|
|
144
|
+
archive,
|
|
142
145
|
resolvedOutputPath,
|
|
143
146
|
existingOutput,
|
|
144
147
|
);
|
|
145
148
|
return {
|
|
146
|
-
...built,
|
|
147
149
|
changed: true,
|
|
148
150
|
outputPath: resolvedOutputPath,
|
|
149
151
|
rollbackCleanupWarning,
|
|
150
152
|
};
|
|
151
153
|
}
|
|
154
|
+
|
|
155
|
+
export async function buildSb3({confirmReplace, outputPath, sourceDirectory, yes = false}) {
|
|
156
|
+
assert(typeof sourceDirectory === 'string', 'SB3 source directory is required.');
|
|
157
|
+
const built = await createDeterministicSb3(sourceDirectory);
|
|
158
|
+
const written = await writeSb3Archive({
|
|
159
|
+
archive: built.archive,
|
|
160
|
+
confirmReplace,
|
|
161
|
+
outputPath,
|
|
162
|
+
yes,
|
|
163
|
+
});
|
|
164
|
+
return {...built, ...written};
|
|
165
|
+
}
|