@kubohiroya/sb3-toolchain 0.2.0 → 0.4.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/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.2.0';
4
+ export const packageVersion = '0.4.0';
@@ -0,0 +1,336 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ import {createHash} from 'node:crypto';
4
+
5
+ import {validateArchiveEntryName} from './archive.js';
6
+
7
+ export const extensionApiManifestFormatVersion = 1;
8
+ export const defaultExtensionApiManifestSizeLimit = 1024 * 1024;
9
+
10
+ function assert(condition, message) {
11
+ if (!condition) {
12
+ throw new Error(message);
13
+ }
14
+ }
15
+
16
+ function isObject(value) {
17
+ return value && typeof value === 'object' && !Array.isArray(value);
18
+ }
19
+
20
+ function assertExactProperties(value, expected, description) {
21
+ const expectedProperties = new Set(expected);
22
+ const unexpected = Object.keys(value).filter((property) => !expectedProperties.has(property));
23
+ assert(
24
+ unexpected.length === 0,
25
+ `${description} has unsupported properties: ${unexpected.join(', ')}`,
26
+ );
27
+ }
28
+
29
+ function assertNonEmptyString(value, description) {
30
+ assert(
31
+ typeof value === 'string' && value.length > 0,
32
+ `${description} must be a non-empty string.`,
33
+ );
34
+ return value;
35
+ }
36
+
37
+ function compareIds(left, right) {
38
+ return left < right ? -1 : left > right ? 1 : 0;
39
+ }
40
+
41
+ function escapeJsonPointer(value) {
42
+ return value.replaceAll('~', '~0').replaceAll('/', '~1');
43
+ }
44
+
45
+ export function extensionApiManifestIntegrity(contents) {
46
+ return `sha256-${createHash('sha256').update(contents).digest('base64')}`;
47
+ }
48
+
49
+ export function extensionApiManifestLocalPath(extensionId) {
50
+ return `extensions/${extensionId}.manifest.json`;
51
+ }
52
+
53
+ export function validateExtensionApiManifestSourceMetadata(extension) {
54
+ const metadata = extension.source?.apiManifest;
55
+ if (metadata === undefined) return null;
56
+ assert(
57
+ isObject(metadata),
58
+ `Managed extension API manifest metadata must be an object: ${extension.id}`,
59
+ );
60
+ assertExactProperties(
61
+ metadata,
62
+ ['artifact', 'formatVersion', 'integrity', 'path'],
63
+ `Managed extension API manifest metadata for ${extension.id}`,
64
+ );
65
+ assert(
66
+ metadata.formatVersion === extensionApiManifestFormatVersion,
67
+ `Managed extension ${extension.id} requires API manifest formatVersion ${extensionApiManifestFormatVersion}.`,
68
+ );
69
+ assertNonEmptyString(
70
+ metadata.artifact,
71
+ `Managed extension ${extension.id} API manifest artifact`,
72
+ );
73
+ validateArchiveEntryName(metadata.artifact);
74
+ assert(
75
+ !metadata.artifact.endsWith('/'),
76
+ `Managed extension API manifest artifact must be a file: ${metadata.artifact}`,
77
+ );
78
+ const expectedPath = extensionApiManifestLocalPath(extension.id);
79
+ assert(
80
+ metadata.path === expectedPath,
81
+ `Managed extension API manifest path must match its ID: expected ${expectedPath}, got ${metadata.path}`,
82
+ );
83
+ assert(
84
+ typeof metadata.integrity === 'string' &&
85
+ /^sha256-[A-Za-z0-9+/]{43}=$/u.test(metadata.integrity),
86
+ `Managed extension ${extension.id} API manifest requires SHA-256 integrity.`,
87
+ );
88
+ return metadata;
89
+ }
90
+
91
+ function normalizeArgument(value, blockOpcode, index, menuIds) {
92
+ assert(isObject(value), `API manifest block ${blockOpcode} argument ${index} must be an object.`);
93
+ assertExactProperties(
94
+ value,
95
+ ['id', 'menu', 'type'],
96
+ `API manifest block ${blockOpcode} argument ${index}`,
97
+ );
98
+ const id = assertNonEmptyString(
99
+ value.id,
100
+ `API manifest block ${blockOpcode} argument ${index} ID`,
101
+ );
102
+ const type = assertNonEmptyString(
103
+ value.type,
104
+ `API manifest block ${blockOpcode} argument ${id} type`,
105
+ );
106
+ if (value.menu !== undefined) {
107
+ assertNonEmptyString(value.menu, `API manifest block ${blockOpcode} argument ${id} menu`);
108
+ assert(
109
+ menuIds.has(value.menu),
110
+ `API manifest block ${blockOpcode} argument ${id} references unknown menu: ${value.menu}`,
111
+ );
112
+ }
113
+ return value.menu === undefined ? {id, type} : {id, menu: value.menu, type};
114
+ }
115
+
116
+ function normalizeBlock(value, index, menuIds) {
117
+ assert(isObject(value), `API manifest block ${index} must be an object.`);
118
+ assertExactProperties(value, ['arguments', 'blockType', 'opcode'], `API manifest block ${index}`);
119
+ const opcode = assertNonEmptyString(value.opcode, `API manifest block ${index} opcode`);
120
+ const blockType = assertNonEmptyString(value.blockType, `API manifest block ${opcode} blockType`);
121
+ assert(
122
+ Array.isArray(value.arguments),
123
+ `API manifest block ${opcode} arguments must be an array.`,
124
+ );
125
+ const arguments_ = value.arguments.map((argument, argumentIndex) =>
126
+ normalizeArgument(argument, opcode, argumentIndex, menuIds),
127
+ );
128
+ const argumentIds = new Set();
129
+ for (const argument of arguments_) {
130
+ assert(
131
+ !argumentIds.has(argument.id),
132
+ `API manifest block ${opcode} has duplicate argument ID: ${argument.id}`,
133
+ );
134
+ argumentIds.add(argument.id);
135
+ }
136
+ arguments_.sort((left, right) => compareIds(left.id, right.id));
137
+ return {arguments: arguments_, blockType, opcode};
138
+ }
139
+
140
+ function normalizeMenu(value, index) {
141
+ assert(isObject(value), `API manifest menu ${index} must be an object.`);
142
+ assertExactProperties(value, ['acceptReporters', 'id'], `API manifest menu ${index}`);
143
+ const id = assertNonEmptyString(value.id, `API manifest menu ${index} ID`);
144
+ assert(
145
+ typeof value.acceptReporters === 'boolean',
146
+ `API manifest menu ${id} acceptReporters must be a boolean.`,
147
+ );
148
+ return {acceptReporters: value.acceptReporters, id};
149
+ }
150
+
151
+ /**
152
+ * @param {string | Uint8Array} contents
153
+ * @param {{expectedId?: string}} [options]
154
+ */
155
+ export function parseExtensionApiManifest(contents, {expectedId} = {}) {
156
+ let manifest;
157
+ try {
158
+ manifest = JSON.parse(Buffer.from(contents).toString('utf8'));
159
+ } catch (error) {
160
+ throw new Error(`Extension API manifest is not valid JSON: ${error.message}`, {cause: error});
161
+ }
162
+ assert(isObject(manifest), 'Extension API manifest must contain an object.');
163
+ assertExactProperties(
164
+ manifest,
165
+ ['blocks', 'formatVersion', 'id', 'menus'],
166
+ 'Extension API manifest',
167
+ );
168
+ assert(
169
+ manifest.formatVersion === extensionApiManifestFormatVersion,
170
+ `Unsupported extension API manifest formatVersion: ${manifest.formatVersion}`,
171
+ );
172
+ assert(
173
+ typeof manifest.id === 'string' && /^[a-z0-9]+$/u.test(manifest.id),
174
+ `Invalid extension API manifest ID: ${JSON.stringify(manifest.id)}`,
175
+ );
176
+ if (expectedId !== undefined) {
177
+ assert(
178
+ manifest.id === expectedId,
179
+ `Extension API manifest ID mismatch: expected ${expectedId}, got ${manifest.id}`,
180
+ );
181
+ }
182
+ assert(Array.isArray(manifest.menus), 'Extension API manifest menus must be an array.');
183
+ const menus = manifest.menus.map(normalizeMenu);
184
+ const menuIds = new Set();
185
+ for (const menu of menus) {
186
+ assert(!menuIds.has(menu.id), `Extension API manifest has duplicate menu ID: ${menu.id}`);
187
+ menuIds.add(menu.id);
188
+ }
189
+ assert(Array.isArray(manifest.blocks), 'Extension API manifest blocks must be an array.');
190
+ const blocks = manifest.blocks.map((block, index) => normalizeBlock(block, index, menuIds));
191
+ const blockOpcodes = new Set();
192
+ for (const block of blocks) {
193
+ assert(
194
+ !blockOpcodes.has(block.opcode),
195
+ `Extension API manifest has duplicate block opcode: ${block.opcode}`,
196
+ );
197
+ blockOpcodes.add(block.opcode);
198
+ }
199
+ blocks.sort((left, right) => compareIds(left.opcode, right.opcode));
200
+ menus.sort((left, right) => compareIds(left.id, right.id));
201
+ return {blocks, formatVersion: extensionApiManifestFormatVersion, id: manifest.id, menus};
202
+ }
203
+
204
+ export function validateManagedExtensionApiManifest(
205
+ extension,
206
+ contents,
207
+ {expectedId = extension.id} = {},
208
+ ) {
209
+ const metadata = validateExtensionApiManifestSourceMetadata(extension);
210
+ if (!metadata) return null;
211
+ const actualIntegrity = extensionApiManifestIntegrity(contents);
212
+ assert(
213
+ actualIntegrity === metadata.integrity,
214
+ `Managed extension API manifest integrity mismatch for ${extension.id}: ` +
215
+ `expected ${metadata.integrity}, got ${actualIntegrity}`,
216
+ );
217
+ const manifest = parseExtensionApiManifest(contents, {expectedId});
218
+ assert(
219
+ manifest.formatVersion === metadata.formatVersion,
220
+ `Managed extension API manifest version mismatch for ${extension.id}.`,
221
+ );
222
+ return {integrity: actualIntegrity, manifest, metadata};
223
+ }
224
+
225
+ function addChange(changes, kind, path, before, after, breaking) {
226
+ changes.push({after, before, breaking, kind, path});
227
+ }
228
+
229
+ export function compareExtensionApiManifests(installed, candidate) {
230
+ const changes = [];
231
+ const installedBlocks = new Map(installed.blocks.map((block) => [block.opcode, block]));
232
+ const candidateBlocks = new Map(candidate.blocks.map((block) => [block.opcode, block]));
233
+ for (const [opcode, block] of installedBlocks) {
234
+ const path = `/blocks/${escapeJsonPointer(opcode)}`;
235
+ const replacement = candidateBlocks.get(opcode);
236
+ if (!replacement) {
237
+ addChange(changes, 'block-removed', path, block, null, true);
238
+ continue;
239
+ }
240
+ if (block.blockType !== replacement.blockType) {
241
+ addChange(
242
+ changes,
243
+ 'block-type-changed',
244
+ `${path}/blockType`,
245
+ block.blockType,
246
+ replacement.blockType,
247
+ true,
248
+ );
249
+ }
250
+ const installedArguments = new Map(block.arguments.map((argument) => [argument.id, argument]));
251
+ const candidateArguments = new Map(
252
+ replacement.arguments.map((argument) => [argument.id, argument]),
253
+ );
254
+ for (const [argumentId, argument] of installedArguments) {
255
+ const argumentPath = `${path}/arguments/${escapeJsonPointer(argumentId)}`;
256
+ const replacementArgument = candidateArguments.get(argumentId);
257
+ if (!replacementArgument) {
258
+ addChange(changes, 'argument-removed', argumentPath, argument, null, true);
259
+ continue;
260
+ }
261
+ for (const property of ['type', 'menu']) {
262
+ if (argument[property] !== replacementArgument[property]) {
263
+ addChange(
264
+ changes,
265
+ `argument-${property}-changed`,
266
+ `${argumentPath}/${property}`,
267
+ argument[property] ?? null,
268
+ replacementArgument[property] ?? null,
269
+ true,
270
+ );
271
+ }
272
+ }
273
+ }
274
+ for (const [argumentId, argument] of candidateArguments) {
275
+ if (!installedArguments.has(argumentId)) {
276
+ addChange(
277
+ changes,
278
+ 'argument-added',
279
+ `${path}/arguments/${escapeJsonPointer(argumentId)}`,
280
+ null,
281
+ argument,
282
+ true,
283
+ );
284
+ }
285
+ }
286
+ }
287
+ for (const [opcode, block] of candidateBlocks) {
288
+ if (!installedBlocks.has(opcode)) {
289
+ addChange(changes, 'block-added', `/blocks/${escapeJsonPointer(opcode)}`, null, block, false);
290
+ }
291
+ }
292
+
293
+ const installedMenus = new Map(installed.menus.map((menu) => [menu.id, menu]));
294
+ const candidateMenus = new Map(candidate.menus.map((menu) => [menu.id, menu]));
295
+ const referencedInstalledMenus = new Set();
296
+ for (const block of installed.blocks) {
297
+ for (const argument of block.arguments) {
298
+ if (argument.menu !== undefined) referencedInstalledMenus.add(argument.menu);
299
+ }
300
+ }
301
+ for (const [menuId, menu] of installedMenus) {
302
+ const path = `/menus/${escapeJsonPointer(menuId)}`;
303
+ const replacement = candidateMenus.get(menuId);
304
+ if (!replacement) {
305
+ addChange(changes, 'menu-removed', path, menu, null, referencedInstalledMenus.has(menuId));
306
+ } else if (menu.acceptReporters !== replacement.acceptReporters) {
307
+ addChange(
308
+ changes,
309
+ 'menu-accept-reporters-changed',
310
+ `${path}/acceptReporters`,
311
+ menu.acceptReporters,
312
+ replacement.acceptReporters,
313
+ true,
314
+ );
315
+ }
316
+ }
317
+ for (const [menuId, menu] of candidateMenus) {
318
+ if (!installedMenus.has(menuId)) {
319
+ addChange(changes, 'menu-added', `/menus/${escapeJsonPointer(menuId)}`, null, menu, false);
320
+ }
321
+ }
322
+ return changes.sort((left, right) =>
323
+ left.path === right.path
324
+ ? compareIds(left.kind, right.kind)
325
+ : compareIds(left.path, right.path),
326
+ );
327
+ }
328
+
329
+ export function formatExtensionApiCompatibilityChanges(extensionId, changes) {
330
+ return changes
331
+ .map(
332
+ (change) =>
333
+ `${extensionId} ${change.breaking ? 'breaking' : 'compatible'} ${change.kind} ${change.path}`,
334
+ )
335
+ .join('\n');
336
+ }
@@ -205,6 +205,14 @@ export function createStaticExtensionBundle(bundle, components, originalProject
205
205
  : opcode;
206
206
  };
207
207
 
208
+ const xmlEscape = (value) => String(value).replace(/[<>&'"]/gu, (character) => ({
209
+ '<': '&lt;',
210
+ '>': '&gt;',
211
+ '&': '&amp;',
212
+ "'": '&apos;',
213
+ '"': '&quot;',
214
+ })[character]);
215
+
208
216
  const installStorageAliases = (storage) => {
209
217
  if (!storage || typeof storage !== 'object') return;
210
218
  const hasBundleStorage = Object.prototype.hasOwnProperty.call(storage, BUNDLE_ID);
@@ -348,8 +356,20 @@ ${loaders}
348
356
  result.blocks.push({
349
357
  blockType: Scratch.BlockType.LABEL,
350
358
  sb3Toolchain: {kind: 'bundle-member-heading', memberId: componentId},
351
- text: '◆ Bundled extension: ' + info.name + ' [' + componentId + '] ◆',
359
+ text: '◆ ' + info.name + ' [' + componentId + '] ◆',
352
360
  });
361
+ if (info.docsURI) {
362
+ const docsURI = String(info.docsURI);
363
+ result.blocks.push({
364
+ blockType: Scratch.BlockType.XML,
365
+ sb3Toolchain: {
366
+ docsURI,
367
+ kind: 'bundle-member-docs',
368
+ memberId: componentId,
369
+ },
370
+ xml: '<button text="Open Documentation" callbackKey="OPEN_EXTENSION_DOCS" callbackData="' + xmlEscape(docsURI) + '"></button>',
371
+ });
372
+ }
353
373
  for (const block of info.blocks || []) {
354
374
  if (block === '---') {
355
375
  result.blocks.push(block);
@@ -3,6 +3,7 @@
3
3
  import {createHash} from 'node:crypto';
4
4
 
5
5
  import {validateArchiveEntryName} from './archive.js';
6
+ import {validateExtensionApiManifestSourceMetadata} from './extension-api-manifest.js';
6
7
 
7
8
  function assert(condition, message) {
8
9
  if (!condition) {
@@ -74,6 +75,7 @@ export function validateExtensionSourceMetadata(extension) {
74
75
  typeof source.integrity === 'string' && /^sha256-[A-Za-z0-9+/]{43}=$/u.test(source.integrity),
75
76
  `Managed extension ${extension.id} requires SHA-256 integrity.`,
76
77
  );
78
+ validateExtensionApiManifestSourceMetadata(extension);
77
79
  return source;
78
80
  }
79
81
 
@@ -3,6 +3,10 @@
3
3
  import {cp, lstat, mkdtemp, readFile, rename, rm, writeFile} from 'node:fs/promises';
4
4
  import path from 'node:path';
5
5
 
6
+ import {
7
+ extensionApiManifestIntegrity,
8
+ parseExtensionApiManifest,
9
+ } from './extension-api-manifest.js';
6
10
  import {extensionHeaderId, extensionIntegrity} from './extension-dependencies.js';
7
11
  import {
8
12
  assertNoInterruptedRollback,
@@ -75,6 +79,7 @@ export function validateNewExtensionId(newId) {
75
79
  }
76
80
 
77
81
  export function rewriteExtensionIdDocuments({
82
+ apiManifestArtifact = undefined,
78
83
  extensionManifest,
79
84
  newId,
80
85
  oldId,
@@ -130,6 +135,7 @@ export function rewriteExtensionIdDocuments({
130
135
  }
131
136
 
132
137
  const counts = {
138
+ apiManifestArtifacts: 0,
133
139
  blockOpcodes: 0,
134
140
  extensionFiles: 1,
135
141
  extensionUrlKeys: 0,
@@ -217,6 +223,45 @@ export function rewriteExtensionIdDocuments({
217
223
  manifestClassified.add(
218
224
  referenceKey('embedded-extensions.json', 'value', `/extensions/${extensionIndex}/path`),
219
225
  );
226
+ let oldApiManifestPath = null;
227
+ let newApiManifestPath = null;
228
+ if (apiManifestArtifact !== undefined) {
229
+ assert(
230
+ extension.source?.apiManifest,
231
+ `Extension ${oldId} has no managed API manifest metadata.`,
232
+ );
233
+ }
234
+ if (extension.source?.apiManifest) {
235
+ oldApiManifestPath = `extensions/${oldId}.manifest.json`;
236
+ newApiManifestPath = `extensions/${newId}.manifest.json`;
237
+ assert(
238
+ extension.source.apiManifest.path === oldApiManifestPath,
239
+ `Extension API manifest path mismatch for ${oldId}: ${extension.source.apiManifest.path}`,
240
+ );
241
+ extension.source.apiManifest.path = newApiManifestPath;
242
+ counts.manifestPaths += 1;
243
+ manifestClassified.add(
244
+ referenceKey(
245
+ 'embedded-extensions.json',
246
+ 'value',
247
+ `/extensions/${extensionIndex}/source/apiManifest/path`,
248
+ ),
249
+ );
250
+ if (
251
+ apiManifestArtifact !== undefined &&
252
+ extension.source.apiManifest.artifact !== apiManifestArtifact
253
+ ) {
254
+ extension.source.apiManifest.artifact = apiManifestArtifact;
255
+ counts.apiManifestArtifacts += 1;
256
+ manifestClassified.add(
257
+ referenceKey(
258
+ 'embedded-extensions.json',
259
+ 'value',
260
+ `/extensions/${extensionIndex}/source/apiManifest/artifact`,
261
+ ),
262
+ );
263
+ }
264
+ }
220
265
  if (sourceArtifact !== undefined) {
221
266
  assert(extension.source, `Extension ${oldId} has no managed source metadata.`);
222
267
  if (extension.source.artifact !== sourceArtifact) {
@@ -251,7 +296,9 @@ export function rewriteExtensionIdDocuments({
251
296
  counts,
252
297
  extensionIndex,
253
298
  extensionManifest: migratedManifest,
299
+ newApiManifestPath,
254
300
  newPath: `extensions/${newId}.js`,
301
+ oldApiManifestPath,
255
302
  oldPath,
256
303
  project: migratedProject,
257
304
  totalChanges,
@@ -297,8 +344,23 @@ async function migrationContext(sourceDirectory, oldId, newId, willReplace) {
297
344
  });
298
345
  const extension = source.extensions[rewrite.extensionIndex];
299
346
  const contents = source.extensionContents.get(oldId);
347
+ const apiManifestContents = source.extensionApiManifestContents.get(oldId) ?? null;
348
+ let apiManifestReady = true;
349
+ if (extension.source?.apiManifest) {
350
+ apiManifestReady =
351
+ apiManifestContents !== null &&
352
+ extensionApiManifestIntegrity(apiManifestContents) === extension.source.apiManifest.integrity;
353
+ if (apiManifestReady) {
354
+ try {
355
+ parseExtensionApiManifest(apiManifestContents, {expectedId: newId});
356
+ } catch {
357
+ apiManifestReady = false;
358
+ }
359
+ }
360
+ }
300
361
  return {
301
- artifactReady: extensionHeaderId(contents) === newId,
362
+ apiManifestContents,
363
+ artifactReady: extensionHeaderId(contents) === newId && apiManifestReady,
302
364
  contents,
303
365
  extension,
304
366
  rewrite,
@@ -372,7 +434,7 @@ export async function migrateExtensionId({fromId, sourceDirectory, toId, yes = f
372
434
  recursive: true,
373
435
  verbatimSymlinks: true,
374
436
  });
375
- await Promise.all([
437
+ const replacements = [
376
438
  writeFile(
377
439
  path.join(candidateDirectory, context.source.sourceManifest.project),
378
440
  `${JSON.stringify(context.rewrite.project, null, 2)}\n`,
@@ -385,7 +447,16 @@ export async function migrateExtensionId({fromId, sourceDirectory, toId, yes = f
385
447
  path.join(candidateDirectory, context.rewrite.oldPath),
386
448
  path.join(candidateDirectory, context.rewrite.newPath),
387
449
  ),
388
- ]);
450
+ ];
451
+ if (context.rewrite.oldApiManifestPath && context.rewrite.newApiManifestPath) {
452
+ replacements.push(
453
+ rename(
454
+ path.join(candidateDirectory, context.rewrite.oldApiManifestPath),
455
+ path.join(candidateDirectory, context.rewrite.newApiManifestPath),
456
+ ),
457
+ );
458
+ }
459
+ await Promise.all(replacements);
389
460
  await createDeterministicSb3(candidateDirectory);
390
461
  const comparison = await compareDirectories(
391
462
  context.source.resolvedSourceDirectory,