@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.
@@ -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.
@@ -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
- - `artifact`: JavaScript artifact path relative to the repository root
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 immutable
102
- `resolvedCommit` and restores local files only when their IDs and hashes match the existing metadata.
103
- `extensions update` resolves `ref` through the GitHub API, downloads both artifacts from that same
104
- commit, and compares a candidate API manifest with the installed contract. It updates
105
- `resolvedCommit` and both integrity values only after compatibility and content validation succeed.
106
- The expanded source is not changed until every selected entry has been downloaded and validated.
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 the GitHub repository, tracked ref,
92
- resolved commit, artifact path, and SHA-256. It can also opt in to a versioned API manifest for static
93
- update compatibility checks. See [`source-format-v1.md`](source-format-v1.md) for the complete schema.
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` | Yes | Yes | No | Check whether a tracked ref has an update |
100
- | `extensions sync` | Yes | No | No | Restore files from the pinned commit |
101
- | `extensions update` | Yes | Yes | Yes | Explicitly update to the latest ref commit |
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. Review upstream changes for extensions whose tracked ref differs
113
- from `resolvedCommit`, then decide whether to update.
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. It downloads from the recorded `resolvedCommit` and
123
- replaces local files only when JavaScript and an optional API manifest match their recorded IDs and
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, compatibility paths, and
152
- both artifacts together, then test the extension's primary features in the generated SB3.
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.4.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
- export async function buildSb3({confirmReplace, outputPath, sourceDirectory, yes = false}) {
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
- arguments_.length === 1 && !arguments_[0].startsWith('-'),
88
- 'The check command requires exactly one SOURCE_DIR.',
125
+ allowedAssetRoots.length === 0 || projectAssetsPath,
126
+ '--allow-asset-root requires --project-assets.',
89
127
  );
90
- return {command: 'check', sourceDirectory: path.resolve(arguments_[0])};
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 === '--output') {
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
- return {command: 'build', outputPath, sourceDirectory, yes};
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 (options.command === 'build' && 'outputPath' in options) {
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
@@ -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.4.0';
4
+ export const packageVersion = '0.6.0';
@@ -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
  '<': '&lt;',
210
218
  '>': '&gt;',
@@ -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
- assert(
47
- source.provider === 'github',
48
- `Unsupported extension source provider for ${extension.id}: ${source.provider}`,
49
- );
50
- assert(
51
- typeof source.repository === 'string' &&
52
- /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9._-]+$/u.test(source.repository),
53
- `Invalid GitHub repository for extension ${extension.id}: ${source.repository}`,
54
- );
55
- assert(
56
- typeof source.ref === 'string' &&
57
- source.ref.length > 0 &&
58
- !/[\u0000-\u0020\u007f]/u.test(source.ref),
59
- `Invalid Git ref for extension ${extension.id}: ${source.ref}`,
60
- );
61
- assert(
62
- typeof source.resolvedCommit === 'string' && /^[a-f0-9]{40}$/u.test(source.resolvedCommit),
63
- `Managed extension ${extension.id} requires a 40-character resolvedCommit.`,
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.`,