@kubohiroya/sb3-toolchain 0.1.1 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +54 -96
- package/docs/extension-bundles.md +446 -0
- package/docs/extension-id-migration.md +34 -32
- package/docs/source-format-v1.md +112 -61
- package/docs/workflows.md +235 -0
- package/package.json +1 -1
- package/src/build.js +21 -7
- package/src/cli.js +149 -2
- package/src/constants.js +1 -1
- package/src/extension-bundle-archive.js +422 -0
- package/src/extension-bundle-configuration.js +247 -0
- package/src/extension-bundle.js +640 -0
- package/src/extension-dependencies.js +14 -1
- package/src/index.js +14 -0
- package/src/source.js +33 -7
package/src/cli.js
CHANGED
|
@@ -6,6 +6,8 @@ import {createInterface} from 'node:readline/promises';
|
|
|
6
6
|
|
|
7
7
|
import {buildSb3} from './build.js';
|
|
8
8
|
import {packageVersion} from './constants.js';
|
|
9
|
+
import {bundleExtensions, unbundleExtensions} from './extension-bundle-configuration.js';
|
|
10
|
+
import {unbundleSb3} from './extension-bundle-archive.js';
|
|
9
11
|
import {migrateExtensionId} from './extension-id-migration.js';
|
|
10
12
|
import {extensionStatus, syncExtensions, updateExtensions} from './extension-sync.js';
|
|
11
13
|
import {importSb3} from './import.js';
|
|
@@ -26,6 +28,9 @@ export function usage() {
|
|
|
26
28
|
sb3-toolchain extensions sync SOURCE_DIR [--yes]
|
|
27
29
|
sb3-toolchain extensions update SOURCE_DIR [EXTENSION_ID] [--migrate-id NEW_ID] [--artifact PATH] [--yes]
|
|
28
30
|
sb3-toolchain extensions migrate-id SOURCE_DIR --from OLD_ID --to NEW_ID [--yes]
|
|
31
|
+
sb3-toolchain extensions bundle SOURCE_DIR --id BUNDLE_ID --name NAME [EXTENSION_ID ...] [--yes]
|
|
32
|
+
sb3-toolchain extensions unbundle SOURCE_DIR BUNDLE_ID [--yes]
|
|
33
|
+
sb3-toolchain extensions unbundle INPUT.sb3 BUNDLE_ID --output OUTPUT.sb3 [--yes]
|
|
29
34
|
|
|
30
35
|
Commands:
|
|
31
36
|
import Expand an SB3 into Git-friendly source files.
|
|
@@ -199,11 +204,105 @@ function parseExtensionIdMigrationArguments(arguments_) {
|
|
|
199
204
|
};
|
|
200
205
|
}
|
|
201
206
|
|
|
207
|
+
function parseExtensionBundleArguments(arguments_) {
|
|
208
|
+
let bundleId;
|
|
209
|
+
let bundleName;
|
|
210
|
+
let sourceDirectory;
|
|
211
|
+
const extensionIds = [];
|
|
212
|
+
let yes = false;
|
|
213
|
+
|
|
214
|
+
for (let index = 0; index < arguments_.length; index += 1) {
|
|
215
|
+
const argument = arguments_[index];
|
|
216
|
+
if (argument === '--id') {
|
|
217
|
+
bundleId = takeValue(arguments_, index, '--id');
|
|
218
|
+
index += 1;
|
|
219
|
+
} else if (argument === '--name') {
|
|
220
|
+
bundleName = takeValue(arguments_, index, '--name');
|
|
221
|
+
index += 1;
|
|
222
|
+
} else if (argument === '--yes') {
|
|
223
|
+
yes = true;
|
|
224
|
+
} else {
|
|
225
|
+
assert(!argument.startsWith('-'), `Unknown option: ${argument}`);
|
|
226
|
+
if (!sourceDirectory) {
|
|
227
|
+
sourceDirectory = path.resolve(argument);
|
|
228
|
+
} else {
|
|
229
|
+
assert(
|
|
230
|
+
/^[a-z0-9]+$/u.test(argument),
|
|
231
|
+
`Bundle member ID must use TurboWarp's [a-z0-9]+ format: ${JSON.stringify(argument)}`,
|
|
232
|
+
);
|
|
233
|
+
extensionIds.push(argument);
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
assert(sourceDirectory, 'The extensions bundle command requires SOURCE_DIR.');
|
|
238
|
+
assert(bundleId, 'The extensions bundle command requires --id BUNDLE_ID.');
|
|
239
|
+
assert(bundleName, 'The extensions bundle command requires --name NAME.');
|
|
240
|
+
return {
|
|
241
|
+
action: 'bundle',
|
|
242
|
+
bundleId,
|
|
243
|
+
bundleName,
|
|
244
|
+
command: 'extensions',
|
|
245
|
+
extensionIds,
|
|
246
|
+
sourceDirectory,
|
|
247
|
+
yes,
|
|
248
|
+
};
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
function parseExtensionUnbundleArguments(arguments_) {
|
|
252
|
+
let bundleId;
|
|
253
|
+
let input;
|
|
254
|
+
let outputPath;
|
|
255
|
+
let yes = false;
|
|
256
|
+
for (let index = 0; index < arguments_.length; index += 1) {
|
|
257
|
+
const argument = arguments_[index];
|
|
258
|
+
if (argument === '--yes') {
|
|
259
|
+
yes = true;
|
|
260
|
+
} else if (argument === '--output') {
|
|
261
|
+
outputPath = path.resolve(takeValue(arguments_, index, '--output'));
|
|
262
|
+
index += 1;
|
|
263
|
+
} else {
|
|
264
|
+
assert(!argument.startsWith('-'), `Unknown option: ${argument}`);
|
|
265
|
+
if (!input) {
|
|
266
|
+
input = path.resolve(argument);
|
|
267
|
+
} else {
|
|
268
|
+
assert(!bundleId, 'Only one BUNDLE_ID may be specified.');
|
|
269
|
+
bundleId = argument;
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
assert(input, 'The extensions unbundle command requires SOURCE_DIR or INPUT.sb3.');
|
|
274
|
+
assert(bundleId, 'The extensions unbundle command requires BUNDLE_ID.');
|
|
275
|
+
if (path.extname(input).toLowerCase() === '.sb3') {
|
|
276
|
+
assert(outputPath, 'SB3 unbundle requires --output OUTPUT.sb3.');
|
|
277
|
+
return {
|
|
278
|
+
action: 'unbundle',
|
|
279
|
+
bundleId,
|
|
280
|
+
command: 'extensions',
|
|
281
|
+
inputPath: input,
|
|
282
|
+
outputPath,
|
|
283
|
+
yes,
|
|
284
|
+
};
|
|
285
|
+
}
|
|
286
|
+
assert(!outputPath, '--output is only valid when unbundling an SB3 file.');
|
|
287
|
+
return {
|
|
288
|
+
action: 'unbundle',
|
|
289
|
+
bundleId,
|
|
290
|
+
command: 'extensions',
|
|
291
|
+
sourceDirectory: input,
|
|
292
|
+
yes,
|
|
293
|
+
};
|
|
294
|
+
}
|
|
295
|
+
|
|
202
296
|
function parseExtensionsArguments(arguments_) {
|
|
203
297
|
const [action, ...actionArguments] = arguments_;
|
|
204
298
|
assert(
|
|
205
|
-
action === '
|
|
206
|
-
|
|
299
|
+
action === 'bundle' ||
|
|
300
|
+
action === 'migrate-id' ||
|
|
301
|
+
action === 'status' ||
|
|
302
|
+
action === 'sync' ||
|
|
303
|
+
action === 'unbundle' ||
|
|
304
|
+
action === 'update',
|
|
305
|
+
'The extensions command requires status, sync, update, migrate-id, bundle, or unbundle.',
|
|
207
306
|
);
|
|
208
307
|
if (action === 'status') {
|
|
209
308
|
assert(
|
|
@@ -219,6 +318,12 @@ function parseExtensionsArguments(arguments_) {
|
|
|
219
318
|
if (action === 'migrate-id') {
|
|
220
319
|
return parseExtensionIdMigrationArguments(actionArguments);
|
|
221
320
|
}
|
|
321
|
+
if (action === 'bundle') {
|
|
322
|
+
return parseExtensionBundleArguments(actionArguments);
|
|
323
|
+
}
|
|
324
|
+
if (action === 'unbundle') {
|
|
325
|
+
return parseExtensionUnbundleArguments(actionArguments);
|
|
326
|
+
}
|
|
222
327
|
return parseExtensionMutationArguments(action, actionArguments);
|
|
223
328
|
}
|
|
224
329
|
|
|
@@ -374,6 +479,48 @@ export async function runCli(
|
|
|
374
479
|
return;
|
|
375
480
|
}
|
|
376
481
|
if (options.command === 'extensions') {
|
|
482
|
+
if (options.action === 'bundle') {
|
|
483
|
+
const result = await bundleExtensions({
|
|
484
|
+
bundleId: options.bundleId,
|
|
485
|
+
bundleName: options.bundleName,
|
|
486
|
+
extensionIds: options.extensionIds,
|
|
487
|
+
sourceDirectory: options.sourceDirectory,
|
|
488
|
+
yes: options.yes,
|
|
489
|
+
});
|
|
490
|
+
log(
|
|
491
|
+
`${result.applied ? 'Configured' : 'Dry run'} extension bundle: ${result.bundleId} ` +
|
|
492
|
+
`(${result.members.join(', ')}).`,
|
|
493
|
+
);
|
|
494
|
+
if (result.rollbackCleanupWarning) log(result.rollbackCleanupWarning);
|
|
495
|
+
return;
|
|
496
|
+
}
|
|
497
|
+
if (options.action === 'unbundle') {
|
|
498
|
+
if ('inputPath' in options) {
|
|
499
|
+
const result = await unbundleSb3({
|
|
500
|
+
bundleId: options.bundleId,
|
|
501
|
+
inputPath: options.inputPath,
|
|
502
|
+
outputPath: options.outputPath,
|
|
503
|
+
yes: options.yes,
|
|
504
|
+
});
|
|
505
|
+
log(
|
|
506
|
+
`${result.applied ? 'Wrote' : 'Dry run'} unbundled SB3: ${result.bundleId} ` +
|
|
507
|
+
`(${result.members.join(', ')}) -> ${result.outputPath}.`,
|
|
508
|
+
);
|
|
509
|
+
if (result.rollbackCleanupWarning) log(result.rollbackCleanupWarning);
|
|
510
|
+
return;
|
|
511
|
+
}
|
|
512
|
+
const result = await unbundleExtensions({
|
|
513
|
+
bundleId: options.bundleId,
|
|
514
|
+
sourceDirectory: options.sourceDirectory,
|
|
515
|
+
yes: options.yes,
|
|
516
|
+
});
|
|
517
|
+
log(
|
|
518
|
+
`${result.applied ? 'Removed' : 'Dry run'} extension bundle: ${result.bundleId} ` +
|
|
519
|
+
`(${result.members.join(', ')}).`,
|
|
520
|
+
);
|
|
521
|
+
if (result.rollbackCleanupWarning) log(result.rollbackCleanupWarning);
|
|
522
|
+
return;
|
|
523
|
+
}
|
|
377
524
|
if (options.action === 'migrate-id') {
|
|
378
525
|
const result = await migrateExtensionId({
|
|
379
526
|
fromId: options.fromId,
|
package/src/constants.js
CHANGED
|
@@ -0,0 +1,422 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MPL-2.0
|
|
2
|
+
|
|
3
|
+
import {lstat, readFile} from 'node:fs/promises';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
|
|
6
|
+
import {strFromU8, strToU8, unzipSync, zipSync} from 'fflate';
|
|
7
|
+
|
|
8
|
+
import {validateArchiveEntryName} from './archive.js';
|
|
9
|
+
import {writeSb3Archive} from './build.js';
|
|
10
|
+
import {extensionBundleRecoveryMarker} from './extension-bundle.js';
|
|
11
|
+
import {extensionHeaderMetadata} from './extension-dependencies.js';
|
|
12
|
+
import {decodeExtensionDataUrl} from './import.js';
|
|
13
|
+
import {fixedZipTimestamp} from './source.js';
|
|
14
|
+
|
|
15
|
+
function assert(condition, message) {
|
|
16
|
+
if (!condition) throw new Error(message);
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function isObject(value) {
|
|
20
|
+
return value && typeof value === 'object' && !Array.isArray(value);
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
function arraysEqual(left, right) {
|
|
24
|
+
return JSON.stringify(left) === JSON.stringify(right);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function validateId(id, description) {
|
|
28
|
+
assert(
|
|
29
|
+
typeof id === 'string' && /^[a-z0-9]+$/u.test(id),
|
|
30
|
+
`${description} must use TurboWarp's [a-z0-9]+ format: ${JSON.stringify(id)}`,
|
|
31
|
+
);
|
|
32
|
+
return id;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function decodeBase64Json(payload, description) {
|
|
36
|
+
assert(
|
|
37
|
+
typeof payload === 'string' && /^[A-Za-z0-9+/]*={0,2}$/u.test(payload),
|
|
38
|
+
`${description} contains invalid base64.`,
|
|
39
|
+
);
|
|
40
|
+
const unpadded = payload.replace(/=+$/u, '');
|
|
41
|
+
assert(unpadded.length % 4 !== 1, `${description} contains invalid base64.`);
|
|
42
|
+
try {
|
|
43
|
+
return JSON.parse(
|
|
44
|
+
Buffer.from(unpadded.padEnd(Math.ceil(unpadded.length / 4) * 4, '='), 'base64').toString(
|
|
45
|
+
'utf8',
|
|
46
|
+
),
|
|
47
|
+
);
|
|
48
|
+
} catch (error) {
|
|
49
|
+
throw new Error(`${description} contains invalid JSON: ${error.message}`, {cause: error});
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
function recoveryPayloadFromSource(source, requiredBundleId = undefined) {
|
|
54
|
+
const prefix = `// ${extensionBundleRecoveryMarker}: `;
|
|
55
|
+
const payloads = source
|
|
56
|
+
.split(/\r?\n/u)
|
|
57
|
+
.filter((line) => line.startsWith(prefix))
|
|
58
|
+
.map((line) => line.slice(prefix.length));
|
|
59
|
+
if (payloads.length === 0) {
|
|
60
|
+
assert(
|
|
61
|
+
requiredBundleId === undefined,
|
|
62
|
+
`Extension ${requiredBundleId} has no ${extensionBundleRecoveryMarker} recovery capsule.`,
|
|
63
|
+
);
|
|
64
|
+
return null;
|
|
65
|
+
}
|
|
66
|
+
assert(payloads.length === 1, 'Bundled extension contains more than one recovery capsule.');
|
|
67
|
+
return payloads[0];
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function validateOriginalOrder(value, description, nullable = false) {
|
|
71
|
+
if (nullable && value === null) return null;
|
|
72
|
+
assert(
|
|
73
|
+
Array.isArray(value) && value.every((id) => typeof id === 'string' && id.length > 0),
|
|
74
|
+
`Recovery capsule ${description} must be an array of IDs${nullable ? ' or null' : ''}.`,
|
|
75
|
+
);
|
|
76
|
+
assert(
|
|
77
|
+
new Set(value).size === value.length,
|
|
78
|
+
`Recovery capsule ${description} contains duplicate IDs.`,
|
|
79
|
+
);
|
|
80
|
+
return [...value];
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
function readRecoveryCapsule(extensionId, dataUrl, required = false) {
|
|
84
|
+
assert(typeof dataUrl === 'string', `Extension URL for ${extensionId} must be a string.`);
|
|
85
|
+
if (!dataUrl.startsWith('data:')) {
|
|
86
|
+
assert(!required, `Extension ${extensionId} is not embedded as a data URL.`);
|
|
87
|
+
return null;
|
|
88
|
+
}
|
|
89
|
+
const decodedBundle = decodeExtensionDataUrl(dataUrl);
|
|
90
|
+
const payload = recoveryPayloadFromSource(
|
|
91
|
+
Buffer.from(decodedBundle.source).toString('utf8'),
|
|
92
|
+
required ? extensionId : undefined,
|
|
93
|
+
);
|
|
94
|
+
if (payload === null) return null;
|
|
95
|
+
const capsule = decodeBase64Json(payload, `Extension ${extensionId} recovery capsule`);
|
|
96
|
+
assert(isObject(capsule), `Extension ${extensionId} recovery capsule must be an object.`);
|
|
97
|
+
assert(
|
|
98
|
+
capsule.formatVersion === 1,
|
|
99
|
+
`Unsupported extension bundle recovery format: ${capsule.formatVersion}`,
|
|
100
|
+
);
|
|
101
|
+
assert(isObject(capsule.bundle), `Extension ${extensionId} recovery capsule has no bundle.`);
|
|
102
|
+
validateId(capsule.bundle.id, 'Recovery capsule bundle ID');
|
|
103
|
+
assert(
|
|
104
|
+
capsule.bundle.id === extensionId,
|
|
105
|
+
`Recovery capsule bundle ID mismatch: expected ${extensionId}, got ${capsule.bundle.id}.`,
|
|
106
|
+
);
|
|
107
|
+
assert(
|
|
108
|
+
typeof capsule.bundle.name === 'string' && capsule.bundle.name.length > 0,
|
|
109
|
+
`Recovery capsule for ${extensionId} has no bundle name.`,
|
|
110
|
+
);
|
|
111
|
+
assert(
|
|
112
|
+
Array.isArray(capsule.components) && capsule.components.length >= 2,
|
|
113
|
+
`Recovery capsule for ${extensionId} must contain at least two components.`,
|
|
114
|
+
);
|
|
115
|
+
|
|
116
|
+
const seenIds = new Set();
|
|
117
|
+
const components = capsule.components.map((component, index) => {
|
|
118
|
+
assert(
|
|
119
|
+
isObject(component),
|
|
120
|
+
`Recovery component ${index} for ${extensionId} must be an object.`,
|
|
121
|
+
);
|
|
122
|
+
validateId(component.id, `Recovery component ${index} ID`);
|
|
123
|
+
assert(!seenIds.has(component.id), `Recovery capsule repeats component: ${component.id}`);
|
|
124
|
+
seenIds.add(component.id);
|
|
125
|
+
const decoded = decodeExtensionDataUrl(component.dataUrl);
|
|
126
|
+
assert(
|
|
127
|
+
decoded.mediaType === 'text/javascript' || decoded.mediaType === 'application/javascript',
|
|
128
|
+
`Recovery component ${component.id} must contain JavaScript.`,
|
|
129
|
+
);
|
|
130
|
+
const metadata = extensionHeaderMetadata(decoded.source);
|
|
131
|
+
assert(
|
|
132
|
+
metadata.id === component.id,
|
|
133
|
+
`Recovery component header ID mismatch: expected ${component.id}, got ${metadata.id ?? '(missing)'}.`,
|
|
134
|
+
);
|
|
135
|
+
return {dataUrl: component.dataUrl, id: component.id};
|
|
136
|
+
});
|
|
137
|
+
|
|
138
|
+
return {
|
|
139
|
+
bundle: {id: capsule.bundle.id, name: capsule.bundle.name},
|
|
140
|
+
components,
|
|
141
|
+
members: components.map((component) => component.id),
|
|
142
|
+
originalExtensionIds: validateOriginalOrder(
|
|
143
|
+
capsule.originalExtensionIds,
|
|
144
|
+
'originalExtensionIds',
|
|
145
|
+
true,
|
|
146
|
+
),
|
|
147
|
+
originalExtensionUrlIds: validateOriginalOrder(
|
|
148
|
+
capsule.originalExtensionUrlIds,
|
|
149
|
+
'originalExtensionUrlIds',
|
|
150
|
+
),
|
|
151
|
+
};
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
function collapseOrder(originalIds, bundles) {
|
|
155
|
+
const bundlesByMember = new Map();
|
|
156
|
+
for (const bundle of bundles) {
|
|
157
|
+
for (const memberId of bundle.members) {
|
|
158
|
+
assert(
|
|
159
|
+
!bundlesByMember.has(memberId),
|
|
160
|
+
`Active extension bundles overlap at member: ${memberId}`,
|
|
161
|
+
);
|
|
162
|
+
bundlesByMember.set(memberId, bundle.bundle.id);
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
const emittedBundles = new Set();
|
|
166
|
+
const output = [];
|
|
167
|
+
for (const id of originalIds) {
|
|
168
|
+
const bundleId = bundlesByMember.get(id);
|
|
169
|
+
if (!bundleId) {
|
|
170
|
+
output.push(id);
|
|
171
|
+
} else if (!emittedBundles.has(bundleId)) {
|
|
172
|
+
emittedBundles.add(bundleId);
|
|
173
|
+
output.push(bundleId);
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
return output;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
function replaceBundledStorage(storage, target, counts) {
|
|
180
|
+
if (!isObject(storage) || !Object.hasOwn(storage, target.bundle.id)) return storage;
|
|
181
|
+
const bundleStorage = storage[target.bundle.id];
|
|
182
|
+
assert(
|
|
183
|
+
isObject(bundleStorage) &&
|
|
184
|
+
bundleStorage.formatVersion === 1 &&
|
|
185
|
+
isObject(bundleStorage.components),
|
|
186
|
+
`Extension storage for ${target.bundle.id} is not a reversible format 1 bundle.`,
|
|
187
|
+
);
|
|
188
|
+
assert(
|
|
189
|
+
Object.keys(bundleStorage).every((key) => key === 'formatVersion' || key === 'components'),
|
|
190
|
+
`Extension storage for ${target.bundle.id} has unsupported bundle-level fields.`,
|
|
191
|
+
);
|
|
192
|
+
const memberIds = new Set(target.members);
|
|
193
|
+
for (const componentId of Object.keys(bundleStorage.components)) {
|
|
194
|
+
assert(
|
|
195
|
+
memberIds.has(componentId),
|
|
196
|
+
`Extension storage for ${target.bundle.id} contains unknown component: ${componentId}`,
|
|
197
|
+
);
|
|
198
|
+
assert(
|
|
199
|
+
!Object.hasOwn(storage, componentId),
|
|
200
|
+
`Cannot restore extension storage because member ID already exists: ${componentId}`,
|
|
201
|
+
);
|
|
202
|
+
}
|
|
203
|
+
const replacement = {};
|
|
204
|
+
for (const [id, value] of Object.entries(storage)) {
|
|
205
|
+
if (id !== target.bundle.id) {
|
|
206
|
+
replacement[id] = value;
|
|
207
|
+
continue;
|
|
208
|
+
}
|
|
209
|
+
for (const memberId of target.members) {
|
|
210
|
+
if (Object.hasOwn(bundleStorage.components, memberId)) {
|
|
211
|
+
replacement[memberId] = bundleStorage.components[memberId];
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
counts.extensionStorage += 1;
|
|
216
|
+
return replacement;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
function restoreOpcodeValues(value, target, counts) {
|
|
220
|
+
if (!value || typeof value !== 'object') return;
|
|
221
|
+
if (Array.isArray(value)) {
|
|
222
|
+
for (const entry of value) restoreOpcodeValues(entry, target, counts);
|
|
223
|
+
return;
|
|
224
|
+
}
|
|
225
|
+
for (const [key, entry] of Object.entries(value)) {
|
|
226
|
+
if (key === 'opcode' && typeof entry === 'string') {
|
|
227
|
+
const bundlePrefix = `${target.bundle.id}_`;
|
|
228
|
+
if (!entry.startsWith(bundlePrefix)) continue;
|
|
229
|
+
const localOpcode = entry.slice(bundlePrefix.length);
|
|
230
|
+
const memberId = target.members.find((id) => localOpcode.startsWith(`${id}__`));
|
|
231
|
+
assert(memberId, `Bundle opcode cannot be assigned to a recovery component: ${entry}`);
|
|
232
|
+
value[key] = `${memberId}_${localOpcode.slice(memberId.length + 2)}`;
|
|
233
|
+
counts.opcodes += 1;
|
|
234
|
+
} else {
|
|
235
|
+
restoreOpcodeValues(entry, target, counts);
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
function collectRemainingBundleReferences(value, bundleId) {
|
|
241
|
+
const references = [];
|
|
242
|
+
const prefix = `${bundleId}_`;
|
|
243
|
+
function visit(current, pointer) {
|
|
244
|
+
if (typeof current === 'string') {
|
|
245
|
+
if (current.startsWith(prefix)) references.push(pointer || '/');
|
|
246
|
+
return;
|
|
247
|
+
}
|
|
248
|
+
if (!current || typeof current !== 'object') return;
|
|
249
|
+
if (Array.isArray(current)) {
|
|
250
|
+
current.forEach((entry, index) => visit(entry, `${pointer}/${index}`));
|
|
251
|
+
return;
|
|
252
|
+
}
|
|
253
|
+
for (const [key, entry] of Object.entries(current)) visit(entry, `${pointer}/${key}`);
|
|
254
|
+
}
|
|
255
|
+
visit(value, '');
|
|
256
|
+
return references;
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
function restoreProject(project, target, activeBundles) {
|
|
260
|
+
const restored = structuredClone(project);
|
|
261
|
+
const counts = {extensionStorage: 0, extensionUrls: 0, opcodes: 0, projectExtensions: 0};
|
|
262
|
+
const remainingBundles = activeBundles.filter((bundle) => bundle.bundle.id !== target.bundle.id);
|
|
263
|
+
|
|
264
|
+
assert(isObject(restored.extensionURLs), 'SB3 project.json extensionURLs must be an object.');
|
|
265
|
+
const currentUrlIds = Object.keys(restored.extensionURLs);
|
|
266
|
+
const expectedUrlIds = collapseOrder(target.originalExtensionUrlIds, activeBundles);
|
|
267
|
+
assert(
|
|
268
|
+
arraysEqual(currentUrlIds, expectedUrlIds),
|
|
269
|
+
`Cannot safely restore extension URL order. Expected ${JSON.stringify(expectedUrlIds)}, ` +
|
|
270
|
+
`got ${JSON.stringify(currentUrlIds)}.`,
|
|
271
|
+
);
|
|
272
|
+
const restoredUrlIds = collapseOrder(target.originalExtensionUrlIds, remainingBundles);
|
|
273
|
+
const componentUrls = new Map(
|
|
274
|
+
target.components.map((component) => [component.id, component.dataUrl]),
|
|
275
|
+
);
|
|
276
|
+
restored.extensionURLs = Object.fromEntries(
|
|
277
|
+
restoredUrlIds.map((id) => [
|
|
278
|
+
id,
|
|
279
|
+
componentUrls.has(id) ? componentUrls.get(id) : restored.extensionURLs[id],
|
|
280
|
+
]),
|
|
281
|
+
);
|
|
282
|
+
counts.extensionUrls = target.members.length + 1;
|
|
283
|
+
|
|
284
|
+
if (target.originalExtensionIds === null) {
|
|
285
|
+
assert(
|
|
286
|
+
restored.extensions === undefined,
|
|
287
|
+
'Cannot safely restore project.extensions because it was added after bundling.',
|
|
288
|
+
);
|
|
289
|
+
} else {
|
|
290
|
+
assert(Array.isArray(restored.extensions), 'SB3 project.json extensions must be an array.');
|
|
291
|
+
const expectedIds = collapseOrder(target.originalExtensionIds, activeBundles);
|
|
292
|
+
assert(
|
|
293
|
+
arraysEqual(restored.extensions, expectedIds),
|
|
294
|
+
`Cannot safely restore project.extensions order. Expected ${JSON.stringify(expectedIds)}, ` +
|
|
295
|
+
`got ${JSON.stringify(restored.extensions)}.`,
|
|
296
|
+
);
|
|
297
|
+
restored.extensions = collapseOrder(target.originalExtensionIds, remainingBundles);
|
|
298
|
+
counts.projectExtensions = target.members.length + 1;
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
restored.extensionStorage = replaceBundledStorage(restored.extensionStorage, target, counts);
|
|
302
|
+
for (const targetEntry of restored.targets ?? []) {
|
|
303
|
+
if (targetEntry) {
|
|
304
|
+
targetEntry.extensionStorage = replaceBundledStorage(
|
|
305
|
+
targetEntry.extensionStorage,
|
|
306
|
+
target,
|
|
307
|
+
counts,
|
|
308
|
+
);
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
restoreOpcodeValues(restored.targets, target, counts);
|
|
313
|
+
restoreOpcodeValues(restored.monitors, target, counts);
|
|
314
|
+
const remainingReferences = collectRemainingBundleReferences(restored, target.bundle.id);
|
|
315
|
+
assert(
|
|
316
|
+
remainingReferences.length === 0,
|
|
317
|
+
`Bundle ${target.bundle.id} has unsupported references at: ` +
|
|
318
|
+
remainingReferences.slice(0, 8).join(', '),
|
|
319
|
+
);
|
|
320
|
+
return {counts, project: restored};
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
function parseProject(projectEntry) {
|
|
324
|
+
try {
|
|
325
|
+
const project = JSON.parse(strFromU8(projectEntry));
|
|
326
|
+
assert(isObject(project), 'SB3 project.json must contain an object.');
|
|
327
|
+
return project;
|
|
328
|
+
} catch (error) {
|
|
329
|
+
if (error.message === 'SB3 project.json must contain an object.') throw error;
|
|
330
|
+
throw new Error(`SB3 project.json is invalid JSON: ${error.message}`, {cause: error});
|
|
331
|
+
}
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
async function createArchiveUnbundlePlan({bundleId, inputPath, outputPath}) {
|
|
335
|
+
validateId(bundleId, 'Extension bundle ID');
|
|
336
|
+
assert(typeof inputPath === 'string', 'Input SB3 path is required.');
|
|
337
|
+
assert(typeof outputPath === 'string', 'Unbundled SB3 output path is required.');
|
|
338
|
+
const resolvedInputPath = path.resolve(inputPath);
|
|
339
|
+
const resolvedOutputPath = path.resolve(outputPath);
|
|
340
|
+
assert(
|
|
341
|
+
path.extname(resolvedInputPath).toLowerCase() === '.sb3',
|
|
342
|
+
`Input path must use the .sb3 extension: ${resolvedInputPath}`,
|
|
343
|
+
);
|
|
344
|
+
assert(
|
|
345
|
+
path.extname(resolvedOutputPath).toLowerCase() === '.sb3',
|
|
346
|
+
`Output path must use the .sb3 extension: ${resolvedOutputPath}`,
|
|
347
|
+
);
|
|
348
|
+
const stats = await lstat(resolvedInputPath);
|
|
349
|
+
assert(
|
|
350
|
+
stats.isFile() && !stats.isSymbolicLink(),
|
|
351
|
+
`Input SB3 must be a regular file, not a symbolic link: ${resolvedInputPath}`,
|
|
352
|
+
);
|
|
353
|
+
const archiveEntries = unzipSync(new Uint8Array(await readFile(resolvedInputPath)));
|
|
354
|
+
const entries = Object.entries(archiveEntries);
|
|
355
|
+
assert(entries.length > 0, 'SB3 archive is empty.');
|
|
356
|
+
for (const [entryName] of entries) {
|
|
357
|
+
validateArchiveEntryName(entryName);
|
|
358
|
+
assert(
|
|
359
|
+
!/^(?:0|[1-9][0-9]*)$/u.test(entryName),
|
|
360
|
+
`Integer-like ZIP entry names cannot preserve archive order: ${entryName}`,
|
|
361
|
+
);
|
|
362
|
+
}
|
|
363
|
+
assert(archiveEntries['project.json'], 'SB3 archive does not contain project.json.');
|
|
364
|
+
const project = parseProject(archiveEntries['project.json']);
|
|
365
|
+
assert(isObject(project.extensionURLs), 'SB3 project.json extensionURLs must be an object.');
|
|
366
|
+
|
|
367
|
+
const activeBundles = [];
|
|
368
|
+
for (const [extensionId, dataUrl] of Object.entries(project.extensionURLs)) {
|
|
369
|
+
const recovery = readRecoveryCapsule(extensionId, dataUrl, extensionId === bundleId);
|
|
370
|
+
if (recovery) activeBundles.push(recovery);
|
|
371
|
+
}
|
|
372
|
+
const target = activeBundles.find((bundle) => bundle.bundle.id === bundleId);
|
|
373
|
+
assert(target, `Reversible extension bundle was not found: ${bundleId}`);
|
|
374
|
+
const restored = restoreProject(project, target, activeBundles);
|
|
375
|
+
const outputEntries = Object.fromEntries(
|
|
376
|
+
entries.map(([entryName, contents]) => [
|
|
377
|
+
entryName,
|
|
378
|
+
entryName === 'project.json' ? strToU8(`${JSON.stringify(restored.project)}\n`) : contents,
|
|
379
|
+
]),
|
|
380
|
+
);
|
|
381
|
+
const archive = zipSync(outputEntries, {level: 6, mtime: fixedZipTimestamp});
|
|
382
|
+
return {
|
|
383
|
+
archive,
|
|
384
|
+
bundleId,
|
|
385
|
+
counts: restored.counts,
|
|
386
|
+
entryCount: entries.length,
|
|
387
|
+
inputPath: resolvedInputPath,
|
|
388
|
+
members: [...target.members],
|
|
389
|
+
outputPath: resolvedOutputPath,
|
|
390
|
+
};
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
function publicArchivePlan(plan) {
|
|
394
|
+
return {
|
|
395
|
+
bundleId: plan.bundleId,
|
|
396
|
+
counts: plan.counts,
|
|
397
|
+
entryCount: plan.entryCount,
|
|
398
|
+
inputPath: plan.inputPath,
|
|
399
|
+
members: plan.members,
|
|
400
|
+
outputPath: plan.outputPath,
|
|
401
|
+
};
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
export async function planBundledSb3Unbundle(options) {
|
|
405
|
+
const plan = await createArchiveUnbundlePlan(options);
|
|
406
|
+
return {applied: false, changed: true, ...publicArchivePlan(plan)};
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
export async function unbundleSb3({bundleId, inputPath, outputPath, yes = false}) {
|
|
410
|
+
const plan = await createArchiveUnbundlePlan({bundleId, inputPath, outputPath});
|
|
411
|
+
const publicPlan = publicArchivePlan(plan);
|
|
412
|
+
if (!yes) {
|
|
413
|
+
return {
|
|
414
|
+
applied: false,
|
|
415
|
+
changed: true,
|
|
416
|
+
...publicPlan,
|
|
417
|
+
rollbackCleanupWarning: null,
|
|
418
|
+
};
|
|
419
|
+
}
|
|
420
|
+
const written = await writeSb3Archive({archive: plan.archive, outputPath: plan.outputPath, yes});
|
|
421
|
+
return {applied: true, ...publicPlan, ...written};
|
|
422
|
+
}
|