@kubohiroya/sb3-toolchain 0.3.0 → 0.5.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/sb3-toolchain",
3
- "version": "0.3.0",
3
+ "version": "0.5.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",
@@ -25,6 +25,7 @@
25
25
  "docs/",
26
26
  "src/",
27
27
  "README.md",
28
+ "README.ja.md",
28
29
  "LICENSE"
29
30
  ],
30
31
  "publishConfig": {
@@ -34,8 +35,8 @@
34
35
  "packageManager": "pnpm@11.11.0",
35
36
  "scripts": {
36
37
  "lint": "eslint src bin test",
37
- "format": "prettier --check .github bin docs src test package.json README.md tsconfig.json",
38
- "format:write": "prettier --write .github bin docs src test package.json README.md tsconfig.json",
38
+ "format": "prettier --check .github bin docs src test package.json README.md README.ja.md tsconfig.json",
39
+ "format:write": "prettier --write .github bin docs src test package.json README.md README.ja.md tsconfig.json",
39
40
  "typecheck": "tsc --project tsconfig.json",
40
41
  "test": "node --test test/*.test.mjs",
41
42
  "pack:check": "npm pack --dry-run --ignore-scripts",
package/src/build.js CHANGED
@@ -152,9 +152,15 @@ export async function writeSb3Archive({
152
152
  };
153
153
  }
154
154
 
155
- export async function buildSb3({confirmReplace, outputPath, sourceDirectory, yes = false}) {
155
+ export async function buildSb3({
156
+ cleanUpBlocks = false,
157
+ confirmReplace,
158
+ outputPath,
159
+ sourceDirectory,
160
+ yes = false,
161
+ }) {
156
162
  assert(typeof sourceDirectory === 'string', 'SB3 source directory is required.');
157
- const built = await createDeterministicSb3(sourceDirectory);
163
+ const built = await createDeterministicSb3(sourceDirectory, {cleanUpBlocks});
158
164
  const written = await writeSb3Archive({
159
165
  archive: built.archive,
160
166
  confirmReplace,
package/src/cli.js CHANGED
@@ -23,7 +23,7 @@ export function usage() {
23
23
  return `Usage:
24
24
  sb3-toolchain import INPUT.sb3 --output SOURCE_DIR [--yes] [--discard-local-changes]
25
25
  sb3-toolchain check SOURCE_DIR
26
- sb3-toolchain build SOURCE_DIR --output OUTPUT.sb3 [--yes]
26
+ sb3-toolchain build SOURCE_DIR --output OUTPUT.sb3 [--clean-up-blocks] [--yes]
27
27
  sb3-toolchain extensions status SOURCE_DIR
28
28
  sb3-toolchain extensions sync SOURCE_DIR [--yes]
29
29
  sb3-toolchain extensions update SOURCE_DIR [EXTENSION_ID] [--migrate-id NEW_ID] [--artifact PATH] [--api-manifest-artifact PATH] [--allow-breaking-api --yes]
@@ -38,6 +38,12 @@ Commands:
38
38
  build Build a deterministic SB3 from expanded sources.
39
39
  extensions Inspect, restore, or update managed embedded extensions.
40
40
 
41
+ Build layout cleanup:
42
+ --clean-up-blocks applies a deterministic TurboWarp-style "Clean up Blocks"
43
+ layout to every target in the generated SB3. It never deletes blocks,
44
+ variables, lists, or comments. The expanded source is unchanged, but the
45
+ generated SB3 might not be able to undo the coordinate changes.
46
+
41
47
  Replacement safety:
42
48
  Differing outputs require interactive confirmation or --yes.
43
49
  Import refuses to discard uncommitted Git changes unless
@@ -91,13 +97,16 @@ function parseCheckArguments(arguments_) {
91
97
  }
92
98
 
93
99
  function parseBuildArguments(arguments_) {
100
+ let cleanUpBlocks = false;
94
101
  let sourceDirectory;
95
102
  let outputPath;
96
103
  let yes = false;
97
104
 
98
105
  for (let index = 0; index < arguments_.length; index += 1) {
99
106
  const argument = arguments_[index];
100
- if (argument === '--output') {
107
+ if (argument === '--clean-up-blocks') {
108
+ cleanUpBlocks = true;
109
+ } else if (argument === '--output') {
101
110
  outputPath = path.resolve(takeValue(arguments_, index, '--output'));
102
111
  index += 1;
103
112
  } else if (argument === '--yes') {
@@ -111,7 +120,13 @@ function parseBuildArguments(arguments_) {
111
120
 
112
121
  assert(sourceDirectory, 'The build command requires SOURCE_DIR.');
113
122
  assert(outputPath, 'The build command requires --output OUTPUT.sb3.');
114
- return {command: 'build', outputPath, sourceDirectory, yes};
123
+ return {
124
+ ...(cleanUpBlocks ? {cleanUpBlocks} : {}),
125
+ command: 'build',
126
+ outputPath,
127
+ sourceDirectory,
128
+ yes,
129
+ };
115
130
  }
116
131
 
117
132
  function parseExtensionMutationArguments(action, arguments_) {
@@ -481,15 +496,20 @@ export async function runCli(
481
496
  }
482
497
  if (options.command === 'build' && 'outputPath' in options) {
483
498
  const result = await buildSb3({
499
+ cleanUpBlocks: options.cleanUpBlocks,
484
500
  confirmReplace: confirmBuildReplacement,
485
501
  outputPath: options.outputPath,
486
502
  sourceDirectory: options.sourceDirectory,
487
503
  yes: options.yes,
488
504
  });
489
505
  const action = result.changed ? 'Built' : 'Already up to date';
506
+ const cleanUpMessage = result.blockCleanUp
507
+ ? `, ${result.blockCleanUp.movedScriptCount}/${result.blockCleanUp.scriptCount} scripts laid out`
508
+ : '';
490
509
  log(
491
510
  `${action}: ${result.outputPath} (${result.entryCount} entries, ` +
492
- `${result.assetCount} assets, ${result.embeddedExtensionCount} embedded extensions).`,
511
+ `${result.assetCount} assets, ${result.embeddedExtensionCount} embedded extensions` +
512
+ `${cleanUpMessage}).`,
493
513
  );
494
514
  if (result.rollbackCleanupWarning) log(result.rollbackCleanupWarning);
495
515
  return;
@@ -557,6 +577,13 @@ export async function runCli(
557
577
  return;
558
578
  }
559
579
  for (const status of statuses) {
580
+ if (status.package) {
581
+ log(
582
+ `${status.id}: ${status.state}; local=${status.local}; ` +
583
+ `${status.package}@${status.version} (installed ${status.installedVersion})`,
584
+ );
585
+ continue;
586
+ }
560
587
  log(
561
588
  `${status.id}: ${status.state}; local=${status.local}; ` +
562
589
  `${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.3.0';
4
+ export const packageVersion = '0.5.0';
@@ -205,6 +205,22 @@ 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
+
216
+ const xmlEscape = (value) => String(value).replace(/[<>&'"]/gu, (character) => ({
217
+ '<': '&lt;',
218
+ '>': '&gt;',
219
+ '&': '&amp;',
220
+ "'": '&apos;',
221
+ '"': '&quot;',
222
+ })[character]);
223
+
208
224
  const installStorageAliases = (storage) => {
209
225
  if (!storage || typeof storage !== 'object') return;
210
226
  const hasBundleStorage = Object.prototype.hasOwnProperty.call(storage, BUNDLE_ID);
@@ -253,6 +269,9 @@ export function createStaticExtensionBundle(bundle, components, originalProject
253
269
  if (property === 'startHats') {
254
270
  return (opcode, ...args) => target.startHats(rewriteOpcode(componentId, opcode), ...args);
255
271
  }
272
+ if (property === 'getOpcodeFunction') {
273
+ return (opcode, ...args) => target.getOpcodeFunction(rewriteBundleOpcode(opcode), ...args);
274
+ }
256
275
  const value = Reflect.get(target, property, target);
257
276
  return typeof value === 'function' ? value.bind(target) : value;
258
277
  },
@@ -348,8 +367,20 @@ ${loaders}
348
367
  result.blocks.push({
349
368
  blockType: Scratch.BlockType.LABEL,
350
369
  sb3Toolchain: {kind: 'bundle-member-heading', memberId: componentId},
351
- text: '◆ Bundled extension: ' + info.name + ' [' + componentId + '] ◆',
370
+ text: '◆ ' + info.name + ' [' + componentId + '] ◆',
352
371
  });
372
+ if (info.docsURI) {
373
+ const docsURI = String(info.docsURI);
374
+ result.blocks.push({
375
+ blockType: Scratch.BlockType.XML,
376
+ sb3Toolchain: {
377
+ docsURI,
378
+ kind: 'bundle-member-docs',
379
+ memberId: componentId,
380
+ },
381
+ xml: '<button text="Open Documentation" callbackKey="OPEN_EXTENSION_DOCS" callbackData="' + xmlEscape(docsURI) + '"></button>',
382
+ });
383
+ }
353
384
  for (const block of info.blocks || []) {
354
385
  if (block === '---') {
355
386
  result.blocks.push(block);
@@ -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.`,
@@ -19,6 +19,7 @@ import {
19
19
  validateManagedExtensionContents,
20
20
  } from './extension-dependencies.js';
21
21
  import {rewriteExtensionIdDocuments, validateNewExtensionId} from './extension-id-migration.js';
22
+ import {readNpmExtensionSource} from './npm-extension-source.js';
22
23
  import {
23
24
  assertNoInterruptedRollback,
24
25
  compareDirectories,
@@ -309,6 +310,9 @@ async function updateCandidate({
309
310
  `Managed extension was not found: ${selectedExtensionId}`,
310
311
  );
311
312
  }
313
+ const selected = managed.filter(
314
+ (extension) => selectedExtensionId === undefined || extension.id === selectedExtensionId,
315
+ );
312
316
  if (migrateToId !== undefined) {
313
317
  assert(mode === 'update', 'Extension ID migration is only available during update.');
314
318
  assert(
@@ -316,6 +320,10 @@ async function updateCandidate({
316
320
  'Extension ID migration requires an explicit existing extension ID.',
317
321
  );
318
322
  validateNewExtensionId(migrateToId);
323
+ assert(
324
+ selected.every((extension) => extension.source.provider === 'github'),
325
+ 'Extension ID migration is not supported for npm-managed extensions.',
326
+ );
319
327
  }
320
328
  assert(
321
329
  sourceArtifact === undefined || migrateToId !== undefined,
@@ -325,9 +333,6 @@ async function updateCandidate({
325
333
  apiManifestArtifact === undefined || migrateToId !== undefined,
326
334
  'A replacement API manifest artifact path requires an extension ID migration.',
327
335
  );
328
- const selected = managed.filter(
329
- (extension) => selectedExtensionId === undefined || extension.id === selectedExtensionId,
330
- );
331
336
  if (migrateToId !== undefined) {
332
337
  const extensionManifest = JSON.parse(
333
338
  await readFile(
@@ -364,23 +369,75 @@ async function updateCandidate({
364
369
  effectiveExtension = {...extension, source: effectiveSource};
365
370
  }
366
371
  validateExtensionSourceMetadata(effectiveExtension);
372
+ if (effectiveExtension.source.provider === 'npm') {
373
+ const npmSource = await readNpmExtensionSource(
374
+ effectiveExtension,
375
+ source.resolvedSourceDirectory,
376
+ {
377
+ allowVersionMismatch: mode === 'update',
378
+ maximumArtifactBytes,
379
+ maximumManifestBytes,
380
+ },
381
+ );
382
+ const apiManifestDownload = npmSource.apiManifestContents
383
+ ? {
384
+ contents: npmSource.apiManifestContents,
385
+ manifest: parseExtensionApiManifest(npmSource.apiManifestContents, {
386
+ expectedId: extension.id,
387
+ }),
388
+ }
389
+ : null;
390
+ let compatibilityChanges = [];
391
+ if (mode === 'sync') {
392
+ validateManagedExtensionContents(extension, npmSource.contents);
393
+ if (apiManifestDownload) {
394
+ validateManagedExtensionApiManifest(extension, apiManifestDownload.contents);
395
+ }
396
+ } else if (apiManifestDownload) {
397
+ const installedApiManifestContents = source.extensionApiManifestContents.get(
398
+ extension.id,
399
+ );
400
+ assert(
401
+ installedApiManifestContents,
402
+ `Managed extension API manifest is missing for ${extension.id}.`,
403
+ );
404
+ const installedApiManifest = validateManagedExtensionApiManifest(
405
+ extension,
406
+ installedApiManifestContents,
407
+ ).manifest;
408
+ compatibilityChanges = compareExtensionApiManifests(
409
+ installedApiManifest,
410
+ apiManifestDownload.manifest,
411
+ );
412
+ }
413
+ return {
414
+ apiManifestDownload,
415
+ commit: null,
416
+ compatibilityChanges,
417
+ contents: npmSource.contents,
418
+ effectiveExtension,
419
+ extension,
420
+ npmVersion: npmSource.version,
421
+ };
422
+ }
423
+ const githubFetch = assertFetch(fetchImplementation);
367
424
  const commit =
368
425
  mode === 'sync'
369
426
  ? extension.source.resolvedCommit
370
- : await resolveGithubCommit(extension, fetchImplementation);
427
+ : await resolveGithubCommit(extension, githubFetch);
371
428
  const expectedId = migrateToId ?? extension.id;
372
429
  const [contents, apiManifestDownload] = await Promise.all([
373
430
  downloadExtension(
374
431
  effectiveExtension,
375
432
  commit,
376
- fetchImplementation,
433
+ githubFetch,
377
434
  maximumArtifactBytes,
378
435
  expectedId,
379
436
  ),
380
437
  downloadExtensionApiManifest(
381
438
  effectiveExtension,
382
439
  commit,
383
- fetchImplementation,
440
+ githubFetch,
384
441
  maximumManifestBytes,
385
442
  expectedId,
386
443
  ),
@@ -461,6 +518,7 @@ async function updateCandidate({
461
518
  contents,
462
519
  effectiveExtension,
463
520
  extension,
521
+ npmVersion,
464
522
  } of downloads) {
465
523
  if (migrateToId !== undefined) {
466
524
  const project = JSON.parse(await readFile(projectPath, 'utf8'));
@@ -511,11 +569,14 @@ async function updateCandidate({
511
569
  const candidateExtension = entriesById.get(extension.id);
512
570
  assert(candidateExtension, `Extension manifest entry disappeared: ${extension.id}`);
513
571
  const integrity = extensionIntegrity(contents);
514
- manifestChanged =
515
- manifestChanged ||
516
- candidateExtension.source.resolvedCommit !== commit ||
517
- candidateExtension.source.integrity !== integrity;
518
- candidateExtension.source.resolvedCommit = commit;
572
+ manifestChanged = manifestChanged || candidateExtension.source.integrity !== integrity;
573
+ if (candidateExtension.source.provider === 'npm') {
574
+ manifestChanged = manifestChanged || candidateExtension.source.version !== npmVersion;
575
+ candidateExtension.source.version = npmVersion;
576
+ } else {
577
+ manifestChanged = manifestChanged || candidateExtension.source.resolvedCommit !== commit;
578
+ candidateExtension.source.resolvedCommit = commit;
579
+ }
519
580
  candidateExtension.source.integrity = integrity;
520
581
  if (apiManifestDownload) {
521
582
  const apiManifestIntegrity = extensionApiManifestIntegrity(apiManifestDownload.contents);
@@ -553,11 +614,19 @@ async function updateCandidate({
553
614
  id: migrateToId ?? extension.id,
554
615
  previousId: migrateToId === undefined ? undefined : extension.id,
555
616
  })),
556
- extensions: downloads.map(({commit, extension}) => ({
557
- id: migrateToId ?? extension.id,
558
- previousId: migrateToId === undefined ? undefined : extension.id,
559
- resolvedCommit: commit,
560
- })),
617
+ extensions: downloads.map(({commit, extension, npmVersion}) =>
618
+ extension.source.provider === 'npm'
619
+ ? {
620
+ id: extension.id,
621
+ package: extension.source.package,
622
+ version: npmVersion,
623
+ }
624
+ : {
625
+ id: migrateToId ?? extension.id,
626
+ previousId: migrateToId === undefined ? undefined : extension.id,
627
+ resolvedCommit: commit,
628
+ },
629
+ ),
561
630
  migration:
562
631
  migration === undefined
563
632
  ? null
@@ -583,10 +652,8 @@ export async function extensionStatus(
583
652
  {fetch: fetchImplementation = globalThis.fetch} = {},
584
653
  ) {
585
654
  const source = await inspectExtensionSource(sourceDirectory);
586
- const fetchFunction = assertFetch(fetchImplementation);
587
655
  return Promise.all(
588
656
  managedExtensions(source).map(async (extension) => {
589
- const remoteCommit = await resolveGithubCommit(extension, fetchFunction);
590
657
  let local = 'valid';
591
658
  try {
592
659
  validateManagedExtensionContents(extension, source.extensionContents.get(extension.id));
@@ -599,6 +666,28 @@ export async function extensionStatus(
599
666
  } catch {
600
667
  local = 'modified';
601
668
  }
669
+ if (extension.source.provider === 'npm') {
670
+ const npmSource = await readNpmExtensionSource(extension, source.resolvedSourceDirectory, {
671
+ allowVersionMismatch: true,
672
+ maximumArtifactBytes: defaultExtensionArtifactSizeLimit,
673
+ maximumManifestBytes: defaultExtensionApiManifestSizeLimit,
674
+ });
675
+ if (npmSource.version === extension.source.version) {
676
+ validateManagedExtensionContents(extension, npmSource.contents);
677
+ if (npmSource.apiManifestContents) {
678
+ validateManagedExtensionApiManifest(extension, npmSource.apiManifestContents);
679
+ }
680
+ }
681
+ return {
682
+ id: extension.id,
683
+ installedVersion: npmSource.version,
684
+ local,
685
+ package: extension.source.package,
686
+ state: npmSource.version === extension.source.version ? 'current' : 'update-available',
687
+ version: extension.source.version,
688
+ };
689
+ }
690
+ const remoteCommit = await resolveGithubCommit(extension, assertFetch(fetchImplementation));
602
691
  return {
603
692
  id: extension.id,
604
693
  local,
@@ -623,7 +712,7 @@ export async function syncExtensions({
623
712
  allowBreakingApi: false,
624
713
  apiManifestArtifact: undefined,
625
714
  confirmReplace,
626
- fetchImplementation: assertFetch(fetchImplementation),
715
+ fetchImplementation,
627
716
  maximumArtifactBytes,
628
717
  maximumManifestBytes,
629
718
  migrateToId: undefined,
@@ -652,7 +741,7 @@ export async function updateExtensions({
652
741
  allowBreakingApi,
653
742
  apiManifestArtifact,
654
743
  confirmReplace,
655
- fetchImplementation: assertFetch(fetchImplementation),
744
+ fetchImplementation,
656
745
  maximumArtifactBytes,
657
746
  maximumManifestBytes,
658
747
  migrateToId,
package/src/index.js CHANGED
@@ -57,3 +57,4 @@ export {
57
57
  sourceFormatVersion,
58
58
  validateSb3Source,
59
59
  } from './source.js';
60
+ export {cleanUpTurboWarpBlocks, turboWarpCleanUpLayout} from './turbowarp-clean-up.js';
@@ -0,0 +1,111 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ import {lstat, readFile, realpath} from 'node:fs/promises';
4
+ import path from 'node:path';
5
+
6
+ import {validateExtensionApiManifestSourceMetadata} from './extension-api-manifest.js';
7
+ import {extensionHeaderId, validateExtensionSourceMetadata} from './extension-dependencies.js';
8
+
9
+ function assert(condition, message) {
10
+ if (!condition) throw new Error(message);
11
+ }
12
+
13
+ function packageSegments(packageName) {
14
+ return packageName.startsWith('@') ? packageName.split('/') : [packageName];
15
+ }
16
+
17
+ async function findPackageDirectory(sourceDirectory, packageName) {
18
+ let current = path.resolve(sourceDirectory);
19
+ while (true) {
20
+ const candidate = path.join(current, 'node_modules', ...packageSegments(packageName));
21
+ try {
22
+ await lstat(path.join(candidate, 'package.json'));
23
+ return candidate;
24
+ } catch (error) {
25
+ if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') throw error;
26
+ }
27
+ const parent = path.dirname(current);
28
+ if (parent === current) break;
29
+ current = parent;
30
+ }
31
+ throw new Error(
32
+ `Installed npm package was not found for managed extension: ${packageName}. Run the project's package manager install command.`,
33
+ );
34
+ }
35
+
36
+ async function readPackageArtifact(packageDirectory, artifact, maximumBytes, description) {
37
+ const [resolvedPackageDirectory, resolvedArtifact] = await Promise.all([
38
+ realpath(packageDirectory),
39
+ realpath(path.join(packageDirectory, ...artifact.split('/'))),
40
+ ]);
41
+ const relativeArtifact = path.relative(resolvedPackageDirectory, resolvedArtifact);
42
+ assert(
43
+ relativeArtifact !== '' &&
44
+ relativeArtifact !== '..' &&
45
+ !relativeArtifact.startsWith(`..${path.sep}`) &&
46
+ !path.isAbsolute(relativeArtifact),
47
+ `${description} resolves outside its npm package: ${artifact}`,
48
+ );
49
+ const stats = await lstat(resolvedArtifact);
50
+ assert(stats.isFile(), `${description} must be a regular file: ${artifact}`);
51
+ assert(stats.size <= maximumBytes, `${description} exceeds the ${maximumBytes}-byte limit.`);
52
+ return readFile(resolvedArtifact);
53
+ }
54
+
55
+ export async function readNpmExtensionSource(
56
+ extension,
57
+ sourceDirectory,
58
+ {allowVersionMismatch = false, maximumArtifactBytes, maximumManifestBytes},
59
+ ) {
60
+ const source = validateExtensionSourceMetadata(extension);
61
+ assert(source?.provider === 'npm', `Extension is not managed by npm: ${extension.id}`);
62
+ const packageDirectory = await findPackageDirectory(sourceDirectory, source.package);
63
+ let packageManifest;
64
+ try {
65
+ packageManifest = JSON.parse(
66
+ await readFile(path.join(packageDirectory, 'package.json'), 'utf8'),
67
+ );
68
+ } catch (error) {
69
+ throw new Error(`Invalid package.json for npm extension ${extension.id}: ${error.message}`, {
70
+ cause: error,
71
+ });
72
+ }
73
+ assert(
74
+ packageManifest?.name === source.package,
75
+ `npm package name mismatch for extension ${extension.id}: expected ${source.package}, got ${packageManifest?.name ?? '(missing)'}`,
76
+ );
77
+ assert(
78
+ typeof packageManifest.version === 'string' &&
79
+ /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(
80
+ packageManifest.version,
81
+ ),
82
+ `npm package has an invalid semantic version for extension ${extension.id}: ${packageManifest?.version ?? '(missing)'}`,
83
+ );
84
+ if (!allowVersionMismatch) {
85
+ assert(
86
+ packageManifest.version === source.version,
87
+ `npm package version mismatch for extension ${extension.id}: expected ${source.version}, got ${packageManifest?.version ?? '(missing)'}`,
88
+ );
89
+ }
90
+ const contents = await readPackageArtifact(
91
+ packageDirectory,
92
+ source.artifact,
93
+ maximumArtifactBytes,
94
+ `npm extension artifact for ${extension.id}`,
95
+ );
96
+ const actualId = extensionHeaderId(contents);
97
+ assert(
98
+ actualId === extension.id,
99
+ `npm extension header ID mismatch for ${extension.id}: expected ${extension.id}, got ${actualId ?? '(missing)'}`,
100
+ );
101
+ const apiMetadata = validateExtensionApiManifestSourceMetadata(extension);
102
+ const apiManifestContents = apiMetadata
103
+ ? await readPackageArtifact(
104
+ packageDirectory,
105
+ apiMetadata.artifact,
106
+ maximumManifestBytes,
107
+ `npm extension API manifest for ${extension.id}`,
108
+ )
109
+ : null;
110
+ return {apiManifestContents, contents, packageDirectory, version: packageManifest.version};
111
+ }
package/src/source.js CHANGED
@@ -13,6 +13,7 @@ import {
13
13
  validateExtensionSourceMetadata,
14
14
  validateManagedExtensionContents,
15
15
  } from './extension-dependencies.js';
16
+ import {cleanUpTurboWarpBlocks} from './turbowarp-clean-up.js';
16
17
 
17
18
  export const sourceFormatVersion = 1;
18
19
  export const fixedZipTimestamp = new Date(1980, 0, 1, 0, 0, 0, 0);
@@ -386,7 +387,8 @@ export async function validateSb3Source(sourceDirectory) {
386
387
  return source;
387
388
  }
388
389
 
389
- export async function createDeterministicSb3(sourceDirectory) {
390
+ export async function createDeterministicSb3(sourceDirectory, {cleanUpBlocks = false} = {}) {
391
+ assert(typeof cleanUpBlocks === 'boolean', 'cleanUpBlocks must be a boolean.');
390
392
  const source = await validateSb3Source(sourceDirectory);
391
393
  const bundled = buildExtensionBundles({
392
394
  extensionBundles: source.extensionBundles,
@@ -394,7 +396,18 @@ export async function createDeterministicSb3(sourceDirectory) {
394
396
  extensions: source.extensions,
395
397
  project: source.project,
396
398
  });
397
- const project = structuredClone(bundled.project);
399
+ let project = structuredClone(bundled.project);
400
+ let blockCleanUp = null;
401
+ if (cleanUpBlocks) {
402
+ const cleaned = cleanUpTurboWarpBlocks(project);
403
+ project = cleaned.project;
404
+ blockCleanUp = {
405
+ movedCommentCount: cleaned.movedCommentCount,
406
+ movedScriptCount: cleaned.movedScriptCount,
407
+ scriptCount: cleaned.scriptCount,
408
+ targetCount: cleaned.targetCount,
409
+ };
410
+ }
398
411
  for (const extension of bundled.extensions) {
399
412
  project.extensionURLs[extension.id] = encodeExtensionDataUrl(
400
413
  extension,
@@ -419,6 +432,7 @@ export async function createDeterministicSb3(sourceDirectory) {
419
432
  archive,
420
433
  assetCount: source.assetContents.size,
421
434
  assetReferenceCount: source.assetReferenceCount,
435
+ blockCleanUp,
422
436
  bundlePlans: bundled.bundlePlans,
423
437
  embeddedExtensionCount: bundled.extensions.length,
424
438
  entryCount: source.sourceManifest.archiveEntries.length,