@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
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# `--project-assets`: project asset build input
|
|
2
|
+
|
|
3
|
+
`--project-assets` adds Stage backdrops, sprite costumes, Stage or sprite sounds, and new sprites to
|
|
4
|
+
a generated SB3 without editing its expanded base source. Both JSON and YAML are supported.
|
|
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` composes and validates the base source and project assets in memory. Only `build` writes an
|
|
18
|
+
SB3. Neither command modifies `project.source.json`, `sb3-source.json`, or the expanded `assets/`.
|
|
19
|
+
|
|
20
|
+
## YAML format (recommended)
|
|
21
|
+
|
|
22
|
+
Like DSL 4.0 `assets:`, `.yml` and `.yaml` use the asset ID as a mapping key and `kind` as the asset
|
|
23
|
+
type. Display properties for newly created sprites are kept separately under `sprites:`.
|
|
24
|
+
|
|
25
|
+
```yaml
|
|
26
|
+
formatVersion: 1
|
|
27
|
+
|
|
28
|
+
sprites:
|
|
29
|
+
Princess:
|
|
30
|
+
layerOrder: 6
|
|
31
|
+
visible: false
|
|
32
|
+
x: 4
|
|
33
|
+
y: -16
|
|
34
|
+
size: 70
|
|
35
|
+
direction: 90
|
|
36
|
+
draggable: false
|
|
37
|
+
rotationStyle: all around
|
|
38
|
+
volume: 100
|
|
39
|
+
|
|
40
|
+
assets:
|
|
41
|
+
Princess:
|
|
42
|
+
kind: costume
|
|
43
|
+
target: Princess
|
|
44
|
+
file: ../../resources/Princess.png
|
|
45
|
+
bitmapResolution: 2
|
|
46
|
+
rotationCenterX: 507
|
|
47
|
+
rotationCenterY: 507
|
|
48
|
+
license: 'CC-BY-SA-4.0: ../../LICENSES.md'
|
|
49
|
+
|
|
50
|
+
DragonCastle:
|
|
51
|
+
kind: backdrop
|
|
52
|
+
file: ../../resources/DragonCastle.svg
|
|
53
|
+
rotationCenterX: 240
|
|
54
|
+
rotationCenterY: 180
|
|
55
|
+
|
|
56
|
+
OpeningSound:
|
|
57
|
+
kind: sound
|
|
58
|
+
file: ../../resources/OpeningSound.mp3
|
|
59
|
+
|
|
60
|
+
PrincessVoice:
|
|
61
|
+
kind: sound
|
|
62
|
+
target: Princess
|
|
63
|
+
file: ../../resources/PrincessVoice.wav
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
- A `backdrop` is added to the Stage `costumes` and does not accept `target`.
|
|
67
|
+
- A `costume` is added to the sprite named by `target`.
|
|
68
|
+
- A `sound` is added to the Stage when `target` is omitted, or to the named sprite otherwise.
|
|
69
|
+
- An existing sprite does not need a duplicate declaration under `sprites:`.
|
|
70
|
+
- A new sprite is declared under `sprites:` and must receive at least one costume from `assets:`.
|
|
71
|
+
- The asset ID becomes its Scratch costume, backdrop, or sound name. Set `name` only to override it.
|
|
72
|
+
|
|
73
|
+
YAML uses version 1.2. Duplicate keys, multiple documents, anchors, aliases, merge keys, custom
|
|
74
|
+
tags, and `__proto__`, `constructor`, or `prototype` keys are rejected. YAML comments are allowed.
|
|
75
|
+
|
|
76
|
+
## JSON format
|
|
77
|
+
|
|
78
|
+
`.json` uses the same fields. The following is equivalent to the Princess part above.
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"formatVersion": 1,
|
|
83
|
+
"sprites": {
|
|
84
|
+
"Princess": {
|
|
85
|
+
"layerOrder": 6,
|
|
86
|
+
"visible": false,
|
|
87
|
+
"x": 4,
|
|
88
|
+
"y": -16,
|
|
89
|
+
"size": 70,
|
|
90
|
+
"direction": 90,
|
|
91
|
+
"draggable": false,
|
|
92
|
+
"rotationStyle": "all around",
|
|
93
|
+
"volume": 100
|
|
94
|
+
}
|
|
95
|
+
},
|
|
96
|
+
"assets": {
|
|
97
|
+
"Princess": {
|
|
98
|
+
"kind": "costume",
|
|
99
|
+
"target": "Princess",
|
|
100
|
+
"file": "../../resources/Princess.png",
|
|
101
|
+
"bitmapResolution": 2,
|
|
102
|
+
"rotationCenterX": 507,
|
|
103
|
+
"rotationCenterY": 507
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Duplicate JSON keys are rejected. Manifest filenames must end in `.json`, `.yml`, or `.yaml`.
|
|
110
|
+
|
|
111
|
+
## Editable mode
|
|
112
|
+
|
|
113
|
+
Omit `size` and `sha256` while repeatedly overwriting an image or audio file. The current file
|
|
114
|
+
bytes are authoritative and the Scratch MD5 `assetId` is recomputed for every build.
|
|
115
|
+
|
|
116
|
+
Images require `kind`, `file`, `rotationCenterX`, and `rotationCenterY`; costumes also require
|
|
117
|
+
`target`. `bitmapResolution` is optional and defaults to `1`. `dataFormat` is inferred from the
|
|
118
|
+
filename extension.
|
|
119
|
+
|
|
120
|
+
Sounds normally require only `kind: sound` and `file`. The open-source `music-metadata` library
|
|
121
|
+
parses MP3 and WAV files to infer `rate` and `sampleCount`. Only a sprite sound also requires
|
|
122
|
+
`target`.
|
|
123
|
+
|
|
124
|
+
## Optional strict locks
|
|
125
|
+
|
|
126
|
+
Add any of these fields when a distribution build must verify its reviewed input:
|
|
127
|
+
|
|
128
|
+
| Field | Check |
|
|
129
|
+
| --------------------- | --------------------------------------- |
|
|
130
|
+
| `size` | Exact file byte length |
|
|
131
|
+
| `sha256` | Exact file SHA-256 |
|
|
132
|
+
| `dataFormat` | Format inferred from the file extension |
|
|
133
|
+
| `rate`, `sampleCount` | Values inferred from an audio file |
|
|
134
|
+
|
|
135
|
+
Each supplied field is checked independently. Omitted fields do not lock content. Optional
|
|
136
|
+
single-line `license` provenance is validated but is not copied into Scratch `project.json`.
|
|
137
|
+
|
|
138
|
+
Identical base source, manifest, asset bytes, and toolchain version produce a bit-for-bit identical
|
|
139
|
+
SB3. Overwriting an asset in editable mode intentionally changes the next build. Add `size` and
|
|
140
|
+
`sha256` when accidental overwrites must fail instead.
|
|
141
|
+
|
|
142
|
+
## Path safety
|
|
143
|
+
|
|
144
|
+
Files are confined to the manifest directory by default. Use repeatable `--allow-asset-root` only
|
|
145
|
+
for intentional shared directories. Absolute paths, escaping an allowed root, symlink traversal,
|
|
146
|
+
special files, format mismatches, and target or asset name collisions are rejected. The manifest
|
|
147
|
+
itself must be a regular file no larger than 1 MiB.
|
|
148
|
+
|
|
149
|
+
## JavaScript API and rollback
|
|
150
|
+
|
|
151
|
+
```js
|
|
152
|
+
await createDeterministicSb3('app', {
|
|
153
|
+
projectAssetsPath: 'stories/my-story/project-assets.yml',
|
|
154
|
+
allowedAssetRoots: ['resources'],
|
|
155
|
+
});
|
|
156
|
+
|
|
157
|
+
await buildSb3({
|
|
158
|
+
sourceDirectory: 'app',
|
|
159
|
+
projectAssetsPath: 'stories/my-story/project-assets.yml',
|
|
160
|
+
allowedAssetRoots: ['resources'],
|
|
161
|
+
outputPath: 'dist/my-story.sb3',
|
|
162
|
+
});
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Omit `projectAssetsPath` to return to the existing build behavior without project additions.
|
package/docs/source-format-v1.md
CHANGED
|
@@ -44,7 +44,7 @@ reconstruct the data URL.
|
|
|
44
44
|
## `embedded-extensions.json`
|
|
45
45
|
|
|
46
46
|
This file records embedded extension data URL information and extraction paths. Optional `source`
|
|
47
|
-
metadata can be added for an extension managed from GitHub.
|
|
47
|
+
metadata can be added for an extension managed from GitHub or an installed npm package.
|
|
48
48
|
|
|
49
49
|
```json
|
|
50
50
|
{
|
|
@@ -75,10 +75,25 @@ metadata can be added for an extension managed from GitHub.
|
|
|
75
75
|
}
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
+
For an exact npm dependency, replace the GitHub-specific fields with the package identity:
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"provider": "npm",
|
|
83
|
+
"package": "@owner/example-extension",
|
|
84
|
+
"version": "1.2.3",
|
|
85
|
+
"artifact": "dist/example.js",
|
|
86
|
+
"integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
- `provider`: `github` or `npm`
|
|
78
91
|
- `repository`: GitHub repository in `<owner>/<repository>` form
|
|
79
92
|
- `ref`: branch, tag, or commit to track for update candidates
|
|
80
93
|
- `resolvedCommit`: lowercase 40-character commit SHA used to obtain the current file
|
|
81
|
-
- `
|
|
94
|
+
- `package`: exact npm package name, including its scope when applicable
|
|
95
|
+
- `version`: exact semantic version recorded in the installed package's `package.json`; ranges are not accepted
|
|
96
|
+
- `artifact`: JavaScript artifact path relative to the repository or npm package root
|
|
82
97
|
- `integrity`: SRI-form SHA-256 of the current file
|
|
83
98
|
- `apiManifest`: optional, opt-in API compatibility metadata
|
|
84
99
|
- `artifact`: API manifest path relative to the same GitHub repository
|
|
@@ -90,7 +105,7 @@ Validation and builds verify managed extensions without accessing the network:
|
|
|
90
105
|
|
|
91
106
|
- The actual file SHA-256 matches `integrity`
|
|
92
107
|
- The file's `// ID: <extensionId>` header matches `id`
|
|
93
|
-
- The repository, ref, commit, and artifact path use safe forms
|
|
108
|
+
- The GitHub repository, ref, commit, npm package, exact version, and artifact path use safe forms
|
|
94
109
|
- When `apiManifest` exists, its JSON schema, ID, format version, path, and SHA-256 are valid
|
|
95
110
|
|
|
96
111
|
Re-importing an SB3 into an existing expanded source directory preserves `source` metadata for the
|
|
@@ -98,12 +113,14 @@ same ID and path. If the imported file does not match the recorded hash or ID, t
|
|
|
98
113
|
without changing the existing output. A new import cannot infer provenance, so it does not create
|
|
99
114
|
`source` automatically.
|
|
100
115
|
|
|
101
|
-
`extensions sync` downloads the JavaScript and optional API manifest using the
|
|
102
|
-
`resolvedCommit
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
`
|
|
106
|
-
|
|
116
|
+
For GitHub sources, `extensions sync` downloads the JavaScript and optional API manifest using the
|
|
117
|
+
immutable `resolvedCommit`. For npm sources, it reads them from the exact package installed in the
|
|
118
|
+
nearest ancestor `node_modules` directory without network access. Both paths restore local files only
|
|
119
|
+
when IDs and hashes match existing metadata. After the package manager installs a newer exact npm
|
|
120
|
+
version, `extensions update` copies its artifacts and updates `version` and integrity metadata.
|
|
121
|
+
GitHub updates instead resolve `ref` and update `resolvedCommit`. Candidate API manifests are compared
|
|
122
|
+
before either type is installed. The expanded source remains unchanged until every selected entry has
|
|
123
|
+
been validated.
|
|
107
124
|
|
|
108
125
|
An extension ID migration changes the manifest `id` and `path`, known references in
|
|
109
126
|
`project.source.json`, and `extensions/<id>.js` in one transaction. When a managed extension is
|
package/docs/workflows.md
CHANGED
|
@@ -83,22 +83,35 @@ expanded format, embedded extension IDs, and SHA-256 hashes using only local inp
|
|
|
83
83
|
and expanded source produce a bit-for-bit identical SB3. An identical existing output is left
|
|
84
84
|
untouched. A differing output requires replacement confirmation or `--yes`.
|
|
85
85
|
|
|
86
|
+
To arrange the top-level scripts in every target before writing the generated SB3, opt in explicitly:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
sb3-toolchain build app --output dist/project.sb3 --clean-up-blocks
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`--clean-up-blocks` uses TurboWarp's cleaned-layout starting coordinates, column grouping tolerance,
|
|
93
|
+
and spacing. It preserves blocks, variables, lists, and comments; attached comments move with their
|
|
94
|
+
scripts. Only the generated `project.json` is transformed, so the expanded source remains unchanged.
|
|
95
|
+
TurboWarp might not be able to undo these coordinate changes after opening the generated SB3. Omit
|
|
96
|
+
the option and rebuild to roll back to the source coordinates.
|
|
97
|
+
|
|
86
98
|
In addition to project-specific tests, open the generated SB3 in TurboWarp and verify startup, primary
|
|
87
99
|
operations, images, sounds, and embedded extension behavior.
|
|
88
100
|
|
|
89
101
|
## Managed embedded extensions
|
|
90
102
|
|
|
91
|
-
The `source` object in `embedded-extensions.json` can record
|
|
92
|
-
|
|
93
|
-
|
|
103
|
+
The `source` object in `embedded-extensions.json` can record either GitHub commit provenance or an
|
|
104
|
+
exact installed npm package version, together with its artifact path and SHA-256. It can also opt in
|
|
105
|
+
to a versioned API manifest for static update compatibility checks. See
|
|
106
|
+
[`source-format-v1.md`](source-format-v1.md) for the complete schema.
|
|
94
107
|
|
|
95
108
|
The extension commands have the following roles:
|
|
96
109
|
|
|
97
110
|
| Command | Network | Resolve ref | Metadata update | Purpose |
|
|
98
111
|
| ----------------------- | ------- | ----------- | --------------- | ------------------------------------------- |
|
|
99
|
-
| `extensions status` |
|
|
100
|
-
| `extensions sync` |
|
|
101
|
-
| `extensions update` |
|
|
112
|
+
| `extensions status` | GitHub | GitHub | No | Check the upstream or installed package |
|
|
113
|
+
| `extensions sync` | GitHub | No | No | Restore files from the declared source |
|
|
114
|
+
| `extensions update` | GitHub | GitHub | Yes | Adopt the upstream or installed package |
|
|
102
115
|
| `extensions migrate-id` | No | No | IDs/references | Migrate an extension ID used by the project |
|
|
103
116
|
| `extensions bundle` | No | No | Bundle config | Combine extensions into one permission unit |
|
|
104
117
|
| `extensions unbundle` | No | No | Config or SB3 | Restore output with individual extensions |
|
|
@@ -109,8 +122,8 @@ The extension commands have the following roles:
|
|
|
109
122
|
sb3-toolchain extensions status app
|
|
110
123
|
```
|
|
111
124
|
|
|
112
|
-
`status` does not change local files.
|
|
113
|
-
|
|
125
|
+
`status` does not change local files. GitHub sources compare the tracked ref with `resolvedCommit`.
|
|
126
|
+
npm sources compare the declared exact version with the installed package without network access.
|
|
114
127
|
|
|
115
128
|
### Restore from a pinned commit
|
|
116
129
|
|
|
@@ -119,9 +132,9 @@ sb3-toolchain extensions sync app
|
|
|
119
132
|
sb3-toolchain check app
|
|
120
133
|
```
|
|
121
134
|
|
|
122
|
-
`sync` does not resolve a mutable branch or tag.
|
|
123
|
-
|
|
124
|
-
SHA-256 values.
|
|
135
|
+
`sync` does not resolve a mutable branch or tag. GitHub sources download from `resolvedCommit`; npm
|
|
136
|
+
sources read from the exact package installed in the nearest ancestor `node_modules`. It replaces
|
|
137
|
+
local files only when JavaScript and an optional API manifest match recorded IDs and SHA-256 values.
|
|
125
138
|
|
|
126
139
|
### Update a tracked ref
|
|
127
140
|
|
|
@@ -135,6 +148,10 @@ git diff -- app
|
|
|
135
148
|
Omitting the ID updates all managed extensions as one transaction. If any download or validation
|
|
136
149
|
fails, neither files nor metadata are changed.
|
|
137
150
|
|
|
151
|
+
For an npm source, first use the project package manager to install a new exact dependency version,
|
|
152
|
+
then run `extensions status` and `extensions update`. The update copies the installed artifacts and
|
|
153
|
+
records their package `version` and integrity. It never queries the npm registry itself.
|
|
154
|
+
|
|
138
155
|
When `source.apiManifest` is present, the update downloads JavaScript and the API manifest from the
|
|
139
156
|
same resolved commit. Compatible additions are reported. A removed block, changed block type,
|
|
140
157
|
argument-contract change, removed referenced menu, or `acceptReporters` change is rejected before
|
|
@@ -148,8 +165,9 @@ sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
|
|
|
148
165
|
See [`extension-api-compatibility.md`](extension-api-compatibility.md) for the versioned manifest
|
|
149
166
|
contract, classification table, default-off behavior, and rollback.
|
|
150
167
|
|
|
151
|
-
In an update PR, review `resolvedCommit`, JavaScript and manifest integrity,
|
|
152
|
-
both artifacts together, then test the extension's primary features in the
|
|
168
|
+
In an update PR, review `resolvedCommit` or npm `version`, JavaScript and manifest integrity,
|
|
169
|
+
compatibility paths, and both artifacts together, then test the extension's primary features in the
|
|
170
|
+
generated SB3.
|
|
153
171
|
|
|
154
172
|
## Migrate an extension ID
|
|
155
173
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kubohiroya/sb3-toolchain",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.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",
|
|
@@ -45,7 +45,9 @@
|
|
|
45
45
|
"prepack": "pnpm check"
|
|
46
46
|
},
|
|
47
47
|
"dependencies": {
|
|
48
|
-
"fflate": "0.8.3"
|
|
48
|
+
"fflate": "0.8.3",
|
|
49
|
+
"music-metadata": "11.14.0",
|
|
50
|
+
"yaml": "2.9.0"
|
|
49
51
|
},
|
|
50
52
|
"devDependencies": {
|
|
51
53
|
"@types/node": "^24.0.0",
|
package/src/build.js
CHANGED
|
@@ -152,9 +152,32 @@ export async function writeSb3Archive({
|
|
|
152
152
|
};
|
|
153
153
|
}
|
|
154
154
|
|
|
155
|
-
|
|
155
|
+
/**
|
|
156
|
+
* @param {{
|
|
157
|
+
* allowedAssetRoots?: string[],
|
|
158
|
+
* cleanUpBlocks?: boolean,
|
|
159
|
+
* confirmReplace?: (outputPath: string) => Promise<boolean>,
|
|
160
|
+
* outputPath: string,
|
|
161
|
+
* projectAssetsPath?: string,
|
|
162
|
+
* sourceDirectory: string,
|
|
163
|
+
* yes?: boolean,
|
|
164
|
+
* }} options
|
|
165
|
+
*/
|
|
166
|
+
export async function buildSb3({
|
|
167
|
+
allowedAssetRoots = [],
|
|
168
|
+
cleanUpBlocks = false,
|
|
169
|
+
confirmReplace,
|
|
170
|
+
outputPath,
|
|
171
|
+
projectAssetsPath,
|
|
172
|
+
sourceDirectory,
|
|
173
|
+
yes = false,
|
|
174
|
+
}) {
|
|
156
175
|
assert(typeof sourceDirectory === 'string', 'SB3 source directory is required.');
|
|
157
|
-
const built = await createDeterministicSb3(sourceDirectory
|
|
176
|
+
const built = await createDeterministicSb3(sourceDirectory, {
|
|
177
|
+
allowedAssetRoots,
|
|
178
|
+
cleanUpBlocks,
|
|
179
|
+
projectAssetsPath,
|
|
180
|
+
});
|
|
158
181
|
const written = await writeSb3Archive({
|
|
159
182
|
archive: built.archive,
|
|
160
183
|
confirmReplace,
|
package/src/cli.js
CHANGED
|
@@ -11,8 +11,13 @@ import {unbundleSb3} from './extension-bundle-archive.js';
|
|
|
11
11
|
import {migrateExtensionId} from './extension-id-migration.js';
|
|
12
12
|
import {extensionStatus, syncExtensions, updateExtensions} from './extension-sync.js';
|
|
13
13
|
import {importSb3} from './import.js';
|
|
14
|
-
import {validateSb3Source} from './source.js';
|
|
14
|
+
import {createDeterministicSb3, validateSb3Source} from './source.js';
|
|
15
15
|
|
|
16
|
+
/**
|
|
17
|
+
* @param {unknown} condition
|
|
18
|
+
* @param {string} message
|
|
19
|
+
* @returns {asserts condition}
|
|
20
|
+
*/
|
|
16
21
|
function assert(condition, message) {
|
|
17
22
|
if (!condition) {
|
|
18
23
|
throw new Error(message);
|
|
@@ -22,8 +27,8 @@ function assert(condition, message) {
|
|
|
22
27
|
export function usage() {
|
|
23
28
|
return `Usage:
|
|
24
29
|
sb3-toolchain import INPUT.sb3 --output SOURCE_DIR [--yes] [--discard-local-changes]
|
|
25
|
-
sb3-toolchain check SOURCE_DIR
|
|
26
|
-
sb3-toolchain build SOURCE_DIR --output OUTPUT.sb3 [--yes]
|
|
30
|
+
sb3-toolchain check SOURCE_DIR [--project-assets MANIFEST.json] [--allow-asset-root DIR ...]
|
|
31
|
+
sb3-toolchain build SOURCE_DIR --output OUTPUT.sb3 [--project-assets MANIFEST.json] [--allow-asset-root DIR ...] [--clean-up-blocks] [--yes]
|
|
27
32
|
sb3-toolchain extensions status SOURCE_DIR
|
|
28
33
|
sb3-toolchain extensions sync SOURCE_DIR [--yes]
|
|
29
34
|
sb3-toolchain extensions update SOURCE_DIR [EXTENSION_ID] [--migrate-id NEW_ID] [--artifact PATH] [--api-manifest-artifact PATH] [--allow-breaking-api --yes]
|
|
@@ -38,6 +43,17 @@ Commands:
|
|
|
38
43
|
build Build a deterministic SB3 from expanded sources.
|
|
39
44
|
extensions Inspect, restore, or update managed embedded extensions.
|
|
40
45
|
|
|
46
|
+
Build layout cleanup:
|
|
47
|
+
--clean-up-blocks applies a deterministic TurboWarp-style "Clean up Blocks"
|
|
48
|
+
layout to every target in the generated SB3. It never deletes blocks,
|
|
49
|
+
variables, lists, or comments. The expanded source is unchanged, but the
|
|
50
|
+
generated SB3 might not be able to undo the coordinate changes.
|
|
51
|
+
|
|
52
|
+
Project asset additions:
|
|
53
|
+
--project-assets validates a JSON or YAML manifest and adds its sprites,
|
|
54
|
+
backdrops, costumes, and sounds only to the generated SB3. Input files are confined to the
|
|
55
|
+
manifest directory unless --allow-asset-root explicitly permits another root.
|
|
56
|
+
|
|
41
57
|
Replacement safety:
|
|
42
58
|
Differing outputs require interactive confirmation or --yes.
|
|
43
59
|
Import refuses to discard uncommitted Git changes unless
|
|
@@ -82,22 +98,64 @@ function parseImportArguments(arguments_) {
|
|
|
82
98
|
return {command: 'import', discardLocalChanges, inputPath, outputDirectory, yes};
|
|
83
99
|
}
|
|
84
100
|
|
|
101
|
+
/**
|
|
102
|
+
* @param {string[]} arguments_
|
|
103
|
+
* @returns {{allowedAssetRoots?: string[], command: 'check', projectAssetsPath?: string, sourceDirectory: string}}
|
|
104
|
+
*/
|
|
85
105
|
function parseCheckArguments(arguments_) {
|
|
106
|
+
const allowedAssetRoots = [];
|
|
107
|
+
let projectAssetsPath;
|
|
108
|
+
let sourceDirectory;
|
|
109
|
+
for (let index = 0; index < arguments_.length; index += 1) {
|
|
110
|
+
const argument = arguments_[index];
|
|
111
|
+
if (argument === '--project-assets') {
|
|
112
|
+
projectAssetsPath = path.resolve(takeValue(arguments_, index, '--project-assets'));
|
|
113
|
+
index += 1;
|
|
114
|
+
} else if (argument === '--allow-asset-root') {
|
|
115
|
+
allowedAssetRoots.push(path.resolve(takeValue(arguments_, index, '--allow-asset-root')));
|
|
116
|
+
index += 1;
|
|
117
|
+
} else {
|
|
118
|
+
assert(!argument.startsWith('-'), `Unknown option: ${argument}`);
|
|
119
|
+
assert(!sourceDirectory, 'Only one SB3 source directory may be specified.');
|
|
120
|
+
sourceDirectory = path.resolve(argument);
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
assert(sourceDirectory, 'The check command requires SOURCE_DIR.');
|
|
86
124
|
assert(
|
|
87
|
-
|
|
88
|
-
'
|
|
125
|
+
allowedAssetRoots.length === 0 || projectAssetsPath,
|
|
126
|
+
'--allow-asset-root requires --project-assets.',
|
|
89
127
|
);
|
|
90
|
-
return {
|
|
128
|
+
return {
|
|
129
|
+
...(allowedAssetRoots.length > 0 ? {allowedAssetRoots} : {}),
|
|
130
|
+
command: 'check',
|
|
131
|
+
...(projectAssetsPath ? {projectAssetsPath} : {}),
|
|
132
|
+
sourceDirectory,
|
|
133
|
+
};
|
|
91
134
|
}
|
|
92
135
|
|
|
136
|
+
/**
|
|
137
|
+
* @param {string[]} arguments_
|
|
138
|
+
* @returns {{allowedAssetRoots?: string[], cleanUpBlocks?: boolean, command: 'build', outputPath: string, projectAssetsPath?: string, sourceDirectory: string, yes: boolean}}
|
|
139
|
+
*/
|
|
93
140
|
function parseBuildArguments(arguments_) {
|
|
141
|
+
const allowedAssetRoots = [];
|
|
142
|
+
let cleanUpBlocks = false;
|
|
94
143
|
let sourceDirectory;
|
|
95
144
|
let outputPath;
|
|
145
|
+
let projectAssetsPath;
|
|
96
146
|
let yes = false;
|
|
97
147
|
|
|
98
148
|
for (let index = 0; index < arguments_.length; index += 1) {
|
|
99
149
|
const argument = arguments_[index];
|
|
100
|
-
if (argument === '--
|
|
150
|
+
if (argument === '--clean-up-blocks') {
|
|
151
|
+
cleanUpBlocks = true;
|
|
152
|
+
} else if (argument === '--project-assets') {
|
|
153
|
+
projectAssetsPath = path.resolve(takeValue(arguments_, index, '--project-assets'));
|
|
154
|
+
index += 1;
|
|
155
|
+
} else if (argument === '--allow-asset-root') {
|
|
156
|
+
allowedAssetRoots.push(path.resolve(takeValue(arguments_, index, '--allow-asset-root')));
|
|
157
|
+
index += 1;
|
|
158
|
+
} else if (argument === '--output') {
|
|
101
159
|
outputPath = path.resolve(takeValue(arguments_, index, '--output'));
|
|
102
160
|
index += 1;
|
|
103
161
|
} else if (argument === '--yes') {
|
|
@@ -111,7 +169,19 @@ function parseBuildArguments(arguments_) {
|
|
|
111
169
|
|
|
112
170
|
assert(sourceDirectory, 'The build command requires SOURCE_DIR.');
|
|
113
171
|
assert(outputPath, 'The build command requires --output OUTPUT.sb3.');
|
|
114
|
-
|
|
172
|
+
assert(
|
|
173
|
+
allowedAssetRoots.length === 0 || projectAssetsPath,
|
|
174
|
+
'--allow-asset-root requires --project-assets.',
|
|
175
|
+
);
|
|
176
|
+
return {
|
|
177
|
+
...(allowedAssetRoots.length > 0 ? {allowedAssetRoots} : {}),
|
|
178
|
+
...(cleanUpBlocks ? {cleanUpBlocks} : {}),
|
|
179
|
+
command: 'build',
|
|
180
|
+
outputPath,
|
|
181
|
+
...(projectAssetsPath ? {projectAssetsPath} : {}),
|
|
182
|
+
sourceDirectory,
|
|
183
|
+
yes,
|
|
184
|
+
};
|
|
115
185
|
}
|
|
116
186
|
|
|
117
187
|
function parseExtensionMutationArguments(action, arguments_) {
|
|
@@ -470,6 +540,22 @@ export async function runCli(
|
|
|
470
540
|
return;
|
|
471
541
|
}
|
|
472
542
|
if (options.command === 'check') {
|
|
543
|
+
assert(
|
|
544
|
+
'sourceDirectory' in options && !('action' in options),
|
|
545
|
+
'Internal CLI check command routing error.',
|
|
546
|
+
);
|
|
547
|
+
if (options.projectAssetsPath) {
|
|
548
|
+
const result = await createDeterministicSb3(options.sourceDirectory, {
|
|
549
|
+
allowedAssetRoots: options.allowedAssetRoots,
|
|
550
|
+
projectAssetsPath: options.projectAssetsPath,
|
|
551
|
+
});
|
|
552
|
+
log(
|
|
553
|
+
`Valid SB3 source with project assets: ${result.source.resolvedSourceDirectory} ` +
|
|
554
|
+
`(${result.entryCount} entries, ${result.assetCount} assets, ` +
|
|
555
|
+
`${result.assetReferenceCount} references, ${result.embeddedExtensionCount} embedded extensions).`,
|
|
556
|
+
);
|
|
557
|
+
return;
|
|
558
|
+
}
|
|
473
559
|
const result = await validateSb3Source(options.sourceDirectory);
|
|
474
560
|
log(
|
|
475
561
|
`Valid SB3 source: ${result.resolvedSourceDirectory} ` +
|
|
@@ -479,17 +565,29 @@ export async function runCli(
|
|
|
479
565
|
);
|
|
480
566
|
return;
|
|
481
567
|
}
|
|
482
|
-
if (
|
|
568
|
+
if (
|
|
569
|
+
options.command === 'build' &&
|
|
570
|
+
'outputPath' in options &&
|
|
571
|
+
'sourceDirectory' in options &&
|
|
572
|
+
!('action' in options)
|
|
573
|
+
) {
|
|
483
574
|
const result = await buildSb3({
|
|
575
|
+
allowedAssetRoots: options.allowedAssetRoots,
|
|
576
|
+
cleanUpBlocks: options.cleanUpBlocks,
|
|
484
577
|
confirmReplace: confirmBuildReplacement,
|
|
485
578
|
outputPath: options.outputPath,
|
|
579
|
+
projectAssetsPath: options.projectAssetsPath,
|
|
486
580
|
sourceDirectory: options.sourceDirectory,
|
|
487
581
|
yes: options.yes,
|
|
488
582
|
});
|
|
489
583
|
const action = result.changed ? 'Built' : 'Already up to date';
|
|
584
|
+
const cleanUpMessage = result.blockCleanUp
|
|
585
|
+
? `, ${result.blockCleanUp.movedScriptCount}/${result.blockCleanUp.scriptCount} scripts laid out`
|
|
586
|
+
: '';
|
|
490
587
|
log(
|
|
491
588
|
`${action}: ${result.outputPath} (${result.entryCount} entries, ` +
|
|
492
|
-
`${result.assetCount} assets, ${result.embeddedExtensionCount} embedded extensions
|
|
589
|
+
`${result.assetCount} assets, ${result.embeddedExtensionCount} embedded extensions` +
|
|
590
|
+
`${cleanUpMessage}).`,
|
|
493
591
|
);
|
|
494
592
|
if (result.rollbackCleanupWarning) log(result.rollbackCleanupWarning);
|
|
495
593
|
return;
|
|
@@ -557,6 +655,13 @@ export async function runCli(
|
|
|
557
655
|
return;
|
|
558
656
|
}
|
|
559
657
|
for (const status of statuses) {
|
|
658
|
+
if (status.package) {
|
|
659
|
+
log(
|
|
660
|
+
`${status.id}: ${status.state}; local=${status.local}; ` +
|
|
661
|
+
`${status.package}@${status.version} (installed ${status.installedVersion})`,
|
|
662
|
+
);
|
|
663
|
+
continue;
|
|
664
|
+
}
|
|
560
665
|
log(
|
|
561
666
|
`${status.id}: ${status.state}; local=${status.local}; ` +
|
|
562
667
|
`${status.ref} -> ${status.remoteCommit} ` +
|
package/src/constants.js
CHANGED
package/src/extension-bundle.js
CHANGED
|
@@ -205,6 +205,14 @@ export function createStaticExtensionBundle(bundle, components, originalProject
|
|
|
205
205
|
: opcode;
|
|
206
206
|
};
|
|
207
207
|
|
|
208
|
+
const rewriteBundleOpcode = (opcode) => {
|
|
209
|
+
for (const componentId of COMPONENT_IDS) {
|
|
210
|
+
const rewritten = rewriteOpcode(componentId, opcode);
|
|
211
|
+
if (rewritten !== opcode) return rewritten;
|
|
212
|
+
}
|
|
213
|
+
return opcode;
|
|
214
|
+
};
|
|
215
|
+
|
|
208
216
|
const xmlEscape = (value) => String(value).replace(/[<>&'"]/gu, (character) => ({
|
|
209
217
|
'<': '<',
|
|
210
218
|
'>': '>',
|
|
@@ -261,6 +269,9 @@ export function createStaticExtensionBundle(bundle, components, originalProject
|
|
|
261
269
|
if (property === 'startHats') {
|
|
262
270
|
return (opcode, ...args) => target.startHats(rewriteOpcode(componentId, opcode), ...args);
|
|
263
271
|
}
|
|
272
|
+
if (property === 'getOpcodeFunction') {
|
|
273
|
+
return (opcode, ...args) => target.getOpcodeFunction(rewriteBundleOpcode(opcode), ...args);
|
|
274
|
+
}
|
|
264
275
|
const value = Reflect.get(target, property, target);
|
|
265
276
|
return typeof value === 'function' ? value.bind(target) : value;
|
|
266
277
|
},
|
|
@@ -43,25 +43,38 @@ export function validateExtensionSourceMetadata(extension) {
|
|
|
43
43
|
source && typeof source === 'object' && !Array.isArray(source),
|
|
44
44
|
`Managed extension source must be an object: ${extension.id}`,
|
|
45
45
|
);
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
46
|
+
if (source.provider === 'github') {
|
|
47
|
+
assert(
|
|
48
|
+
typeof source.repository === 'string' &&
|
|
49
|
+
/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9._-]+$/u.test(source.repository),
|
|
50
|
+
`Invalid GitHub repository for extension ${extension.id}: ${source.repository}`,
|
|
51
|
+
);
|
|
52
|
+
assert(
|
|
53
|
+
typeof source.ref === 'string' &&
|
|
54
|
+
source.ref.length > 0 &&
|
|
55
|
+
!/[\u0000-\u0020\u007f]/u.test(source.ref),
|
|
56
|
+
`Invalid Git ref for extension ${extension.id}: ${source.ref}`,
|
|
57
|
+
);
|
|
58
|
+
assert(
|
|
59
|
+
typeof source.resolvedCommit === 'string' && /^[a-f0-9]{40}$/u.test(source.resolvedCommit),
|
|
60
|
+
`Managed extension ${extension.id} requires a 40-character resolvedCommit.`,
|
|
61
|
+
);
|
|
62
|
+
} else if (source.provider === 'npm') {
|
|
63
|
+
assert(
|
|
64
|
+
typeof source.package === 'string' &&
|
|
65
|
+
/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u.test(source.package),
|
|
66
|
+
`Invalid npm package for extension ${extension.id}: ${source.package}`,
|
|
67
|
+
);
|
|
68
|
+
assert(
|
|
69
|
+
typeof source.version === 'string' &&
|
|
70
|
+
/^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(source.version),
|
|
71
|
+
`Managed npm extension ${extension.id} requires an exact semantic version.`,
|
|
72
|
+
);
|
|
73
|
+
} else {
|
|
74
|
+
throw new Error(
|
|
75
|
+
`Unsupported extension source provider for ${extension.id}: ${source.provider}`,
|
|
76
|
+
);
|
|
77
|
+
}
|
|
65
78
|
assert(
|
|
66
79
|
typeof source.artifact === 'string' && source.artifact.length > 0,
|
|
67
80
|
`Managed extension ${extension.id} requires an artifact path.`,
|