@kubohiroya/sb3-toolchain 0.1.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/LICENSE +373 -0
- package/README.md +187 -0
- package/bin/sb3-toolchain.mjs +9 -0
- package/docs/extension-id-migration.md +59 -0
- package/docs/source-format-v1.md +119 -0
- package/package.json +62 -0
- package/src/archive.js +35 -0
- package/src/build.js +151 -0
- package/src/cli.js +465 -0
- package/src/constants.js +4 -0
- package/src/extension-dependencies.js +86 -0
- package/src/extension-id-migration.js +425 -0
- package/src/extension-sync.js +496 -0
- package/src/import.js +381 -0
- package/src/index.js +34 -0
- package/src/output-safety.js +322 -0
- package/src/source.js +386 -0
package/src/import.js
ADDED
|
@@ -0,0 +1,381 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MPL-2.0
|
|
2
|
+
|
|
3
|
+
import {mkdir, mkdtemp, readFile, rm, writeFile} from 'node:fs/promises';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import process from 'node:process';
|
|
6
|
+
|
|
7
|
+
import {strFromU8, unzipSync} from 'fflate';
|
|
8
|
+
|
|
9
|
+
import {validateArchiveEntryName} from './archive.js';
|
|
10
|
+
import {validateManagedExtensionContents} from './extension-dependencies.js';
|
|
11
|
+
import {
|
|
12
|
+
assertNoInterruptedRollback,
|
|
13
|
+
assertRecognizedOutputDirectory,
|
|
14
|
+
compareDirectories,
|
|
15
|
+
inspectGitOutputState,
|
|
16
|
+
pathExists,
|
|
17
|
+
replaceDirectoryTransactionally,
|
|
18
|
+
validateOutputDirectoryPath,
|
|
19
|
+
} from './output-safety.js';
|
|
20
|
+
import {sourceFormatVersion} from './source.js';
|
|
21
|
+
|
|
22
|
+
export {validateOutputDirectoryPath} from './output-safety.js';
|
|
23
|
+
|
|
24
|
+
function assert(condition, message) {
|
|
25
|
+
if (!condition) {
|
|
26
|
+
throw new Error(message);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
function summarizeGitChanges(gitState) {
|
|
31
|
+
const entries = [
|
|
32
|
+
...gitState.statusEntries,
|
|
33
|
+
...gitState.untrackedContent.map((entry) => `not tracked: ${entry}`),
|
|
34
|
+
];
|
|
35
|
+
const visibleEntries = entries.slice(0, 8).join(', ');
|
|
36
|
+
const remainder = entries.length > 8 ? `, and ${entries.length - 8} more` : '';
|
|
37
|
+
return `${visibleEntries}${remainder}`;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
async function authorizeOutputReplacement({
|
|
41
|
+
candidateDirectory,
|
|
42
|
+
confirmReplace,
|
|
43
|
+
discardLocalChanges,
|
|
44
|
+
outputDirectory,
|
|
45
|
+
yes,
|
|
46
|
+
}) {
|
|
47
|
+
await assertNoInterruptedRollback(outputDirectory);
|
|
48
|
+
if (!(await pathExists(outputDirectory))) {
|
|
49
|
+
return {action: 'create', comparison: null, gitState: null};
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
await assertRecognizedOutputDirectory(outputDirectory, sourceFormatVersion);
|
|
53
|
+
const comparison = await compareDirectories(outputDirectory, candidateDirectory);
|
|
54
|
+
if (comparison.identical) {
|
|
55
|
+
return {action: 'unchanged', comparison, gitState: null};
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
const gitState = await inspectGitOutputState(outputDirectory, comparison.existingFilePaths);
|
|
59
|
+
assert(
|
|
60
|
+
gitState.managed,
|
|
61
|
+
`Existing output differs from the SB3 candidate but is not tracked by Git: ${outputDirectory}. ` +
|
|
62
|
+
'Import to a new output directory instead of replacing unrecoverable content.',
|
|
63
|
+
);
|
|
64
|
+
assert(
|
|
65
|
+
gitState.clean || discardLocalChanges,
|
|
66
|
+
`Existing output differs from the SB3 candidate and has uncommitted Git changes: ` +
|
|
67
|
+
`${summarizeGitChanges(gitState)}. Commit or stash them first, or explicitly use ` +
|
|
68
|
+
'--discard-local-changes.',
|
|
69
|
+
);
|
|
70
|
+
|
|
71
|
+
const context = {
|
|
72
|
+
comparison,
|
|
73
|
+
discardLocalChanges,
|
|
74
|
+
gitState,
|
|
75
|
+
outputDirectory,
|
|
76
|
+
};
|
|
77
|
+
if (yes) {
|
|
78
|
+
return {action: 'replace', ...context};
|
|
79
|
+
}
|
|
80
|
+
assert(
|
|
81
|
+
typeof confirmReplace === 'function',
|
|
82
|
+
`Output directory already exists: ${outputDirectory}. ` +
|
|
83
|
+
'Refusing to replace differing content without interactive confirmation or --yes.',
|
|
84
|
+
);
|
|
85
|
+
assert(
|
|
86
|
+
await confirmReplace(context),
|
|
87
|
+
'SB3 import cancelled; the existing output was not changed.',
|
|
88
|
+
);
|
|
89
|
+
return {action: 'replace', ...context};
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
async function revalidateOutputReplacement({
|
|
93
|
+
candidateDirectory,
|
|
94
|
+
decision,
|
|
95
|
+
discardLocalChanges,
|
|
96
|
+
outputDirectory,
|
|
97
|
+
}) {
|
|
98
|
+
const latestComparison = await compareDirectories(outputDirectory, candidateDirectory);
|
|
99
|
+
assert(
|
|
100
|
+
latestComparison.existingFingerprint === decision.comparison.existingFingerprint &&
|
|
101
|
+
latestComparison.candidateFingerprint === decision.comparison.candidateFingerprint,
|
|
102
|
+
'Output or candidate content changed during SB3 import; refusing to replace it.',
|
|
103
|
+
);
|
|
104
|
+
const latestGitState = await inspectGitOutputState(
|
|
105
|
+
outputDirectory,
|
|
106
|
+
latestComparison.existingFilePaths,
|
|
107
|
+
);
|
|
108
|
+
assert(
|
|
109
|
+
latestGitState.managed,
|
|
110
|
+
'Output stopped being Git-managed during SB3 import; refusing to replace it.',
|
|
111
|
+
);
|
|
112
|
+
assert(
|
|
113
|
+
latestGitState.fingerprint === decision.gitState.fingerprint,
|
|
114
|
+
'Git state changed during SB3 import; refusing to replace the output.',
|
|
115
|
+
);
|
|
116
|
+
assert(
|
|
117
|
+
latestGitState.clean || discardLocalChanges,
|
|
118
|
+
'Output gained uncommitted Git changes during SB3 import; refusing to replace it.',
|
|
119
|
+
);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
function extensionSourcePath(extensionId) {
|
|
123
|
+
assert(
|
|
124
|
+
/^[A-Za-z0-9._-]+$/u.test(extensionId),
|
|
125
|
+
`Embedded extension ID cannot be used as a filename: ${JSON.stringify(extensionId)}`,
|
|
126
|
+
);
|
|
127
|
+
return `extensions/${extensionId}.js`;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
async function readExistingExtensionSources(outputDirectory) {
|
|
131
|
+
if (!(await pathExists(outputDirectory))) {
|
|
132
|
+
return new Map();
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
const manifestPath = path.join(outputDirectory, 'embedded-extensions.json');
|
|
136
|
+
if (!(await pathExists(manifestPath))) {
|
|
137
|
+
return new Map();
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
let manifest;
|
|
141
|
+
try {
|
|
142
|
+
manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
|
|
143
|
+
} catch (error) {
|
|
144
|
+
throw new Error(`Existing embedded extension manifest is not valid JSON: ${manifestPath}`, {
|
|
145
|
+
cause: error,
|
|
146
|
+
});
|
|
147
|
+
}
|
|
148
|
+
assert(
|
|
149
|
+
manifest &&
|
|
150
|
+
typeof manifest === 'object' &&
|
|
151
|
+
!Array.isArray(manifest) &&
|
|
152
|
+
Array.isArray(manifest.extensions),
|
|
153
|
+
`Existing embedded extension manifest is invalid: ${manifestPath}`,
|
|
154
|
+
);
|
|
155
|
+
|
|
156
|
+
return new Map(
|
|
157
|
+
manifest.extensions
|
|
158
|
+
.filter(
|
|
159
|
+
(extension) =>
|
|
160
|
+
extension &&
|
|
161
|
+
typeof extension === 'object' &&
|
|
162
|
+
typeof extension.id === 'string' &&
|
|
163
|
+
typeof extension.path === 'string' &&
|
|
164
|
+
extension.source !== undefined,
|
|
165
|
+
)
|
|
166
|
+
.map((extension) => [`${extension.id}\u0000${extension.path}`, extension.source]),
|
|
167
|
+
);
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
export function decodeExtensionDataUrl(dataUrl) {
|
|
171
|
+
assert(
|
|
172
|
+
typeof dataUrl === 'string' && dataUrl.startsWith('data:'),
|
|
173
|
+
'Embedded extension URL must be a data URL.',
|
|
174
|
+
);
|
|
175
|
+
const commaIndex = dataUrl.indexOf(',');
|
|
176
|
+
assert(commaIndex >= 0, 'Embedded extension data URL has no payload separator.');
|
|
177
|
+
|
|
178
|
+
const metadata = dataUrl.slice('data:'.length, commaIndex).split(';');
|
|
179
|
+
const mediaType = metadata.shift() || 'text/plain';
|
|
180
|
+
const base64Index = metadata.indexOf('base64');
|
|
181
|
+
const encoding = base64Index >= 0 ? 'base64' : 'percent';
|
|
182
|
+
if (base64Index >= 0) {
|
|
183
|
+
metadata.splice(base64Index, 1);
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
const payload = dataUrl.slice(commaIndex + 1);
|
|
187
|
+
let source;
|
|
188
|
+
if (encoding === 'base64') {
|
|
189
|
+
assert(
|
|
190
|
+
/^[A-Za-z0-9+/]*={0,2}$/u.test(payload),
|
|
191
|
+
'Embedded extension data URL contains invalid base64.',
|
|
192
|
+
);
|
|
193
|
+
const unpaddedPayload = payload.replace(/=+$/u, '');
|
|
194
|
+
assert(
|
|
195
|
+
unpaddedPayload.length % 4 !== 1,
|
|
196
|
+
'Embedded extension data URL contains invalid base64.',
|
|
197
|
+
);
|
|
198
|
+
source = Buffer.from(
|
|
199
|
+
unpaddedPayload.padEnd(Math.ceil(unpaddedPayload.length / 4) * 4, '='),
|
|
200
|
+
'base64',
|
|
201
|
+
);
|
|
202
|
+
} else {
|
|
203
|
+
try {
|
|
204
|
+
source = Buffer.from(decodeURIComponent(payload), 'utf8');
|
|
205
|
+
} catch {
|
|
206
|
+
throw new Error('Embedded extension data URL contains invalid percent encoding.');
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
return {
|
|
211
|
+
encoding,
|
|
212
|
+
mediaType,
|
|
213
|
+
parameters: metadata,
|
|
214
|
+
source,
|
|
215
|
+
};
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
export async function importSb3({
|
|
219
|
+
inputPath,
|
|
220
|
+
outputDirectory,
|
|
221
|
+
protectedRoot = process.cwd(),
|
|
222
|
+
discardLocalChanges = false,
|
|
223
|
+
yes = false,
|
|
224
|
+
confirmReplace,
|
|
225
|
+
}) {
|
|
226
|
+
assert(typeof inputPath === 'string', 'Input SB3 path is required.');
|
|
227
|
+
assert(typeof outputDirectory === 'string', 'SB3 source output directory is required.');
|
|
228
|
+
const resolvedInputPath = path.resolve(inputPath);
|
|
229
|
+
const resolvedOutputDirectory = validateOutputDirectoryPath(outputDirectory, protectedRoot);
|
|
230
|
+
|
|
231
|
+
const archive = unzipSync(new Uint8Array(await readFile(resolvedInputPath)));
|
|
232
|
+
const archiveEntries = Object.entries(archive);
|
|
233
|
+
assert(archiveEntries.length > 0, 'SB3 archive is empty.');
|
|
234
|
+
for (const [entryName] of archiveEntries) {
|
|
235
|
+
validateArchiveEntryName(entryName);
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
const projectEntry = archive['project.json'];
|
|
239
|
+
assert(projectEntry, 'SB3 archive does not contain project.json.');
|
|
240
|
+
|
|
241
|
+
let project;
|
|
242
|
+
let decision;
|
|
243
|
+
let rollbackCleanupWarning = null;
|
|
244
|
+
try {
|
|
245
|
+
project = JSON.parse(strFromU8(projectEntry));
|
|
246
|
+
} catch (error) {
|
|
247
|
+
throw new Error(`SB3 project.json is invalid JSON: ${error.message}`, {cause: error});
|
|
248
|
+
}
|
|
249
|
+
assert(
|
|
250
|
+
project && typeof project === 'object' && !Array.isArray(project),
|
|
251
|
+
'SB3 project.json must contain a JSON object.',
|
|
252
|
+
);
|
|
253
|
+
|
|
254
|
+
const extensionUrls = project.extensionURLs ?? {};
|
|
255
|
+
assert(
|
|
256
|
+
extensionUrls && typeof extensionUrls === 'object' && !Array.isArray(extensionUrls),
|
|
257
|
+
'SB3 project.json extensionURLs must be an object when present.',
|
|
258
|
+
);
|
|
259
|
+
|
|
260
|
+
const existingExtensionSources = await readExistingExtensionSources(resolvedOutputDirectory);
|
|
261
|
+
const embeddedExtensions = [];
|
|
262
|
+
const decodedExtensionSources = [];
|
|
263
|
+
for (const [extensionId, extensionUrl] of Object.entries(extensionUrls)) {
|
|
264
|
+
if (typeof extensionUrl !== 'string' || !extensionUrl.startsWith('data:')) {
|
|
265
|
+
continue;
|
|
266
|
+
}
|
|
267
|
+
const sourcePath = extensionSourcePath(extensionId);
|
|
268
|
+
const decoded = decodeExtensionDataUrl(extensionUrl);
|
|
269
|
+
extensionUrls[extensionId] = `embedded-extension:${sourcePath}`;
|
|
270
|
+
const extension = {
|
|
271
|
+
id: extensionId,
|
|
272
|
+
path: sourcePath,
|
|
273
|
+
mediaType: decoded.mediaType,
|
|
274
|
+
parameters: decoded.parameters,
|
|
275
|
+
encoding: decoded.encoding,
|
|
276
|
+
};
|
|
277
|
+
const existingSource = existingExtensionSources.get(`${extensionId}\u0000${sourcePath}`);
|
|
278
|
+
if (existingSource !== undefined) {
|
|
279
|
+
extension.source = structuredClone(existingSource);
|
|
280
|
+
validateManagedExtensionContents(extension, decoded.source);
|
|
281
|
+
}
|
|
282
|
+
embeddedExtensions.push(extension);
|
|
283
|
+
decodedExtensionSources.push({path: sourcePath, source: decoded.source});
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
const outputParent = path.dirname(resolvedOutputDirectory);
|
|
287
|
+
await mkdir(outputParent, {recursive: true});
|
|
288
|
+
const temporaryDirectory = await mkdtemp(
|
|
289
|
+
path.join(outputParent, `.${path.basename(resolvedOutputDirectory)}.import-`),
|
|
290
|
+
);
|
|
291
|
+
|
|
292
|
+
try {
|
|
293
|
+
const assetsDirectory = path.join(temporaryDirectory, 'assets');
|
|
294
|
+
await mkdir(assetsDirectory, {recursive: true});
|
|
295
|
+
await mkdir(path.join(temporaryDirectory, 'extensions'), {recursive: true});
|
|
296
|
+
|
|
297
|
+
for (const [entryName, contents] of archiveEntries) {
|
|
298
|
+
if (entryName === 'project.json' || entryName.endsWith('/')) {
|
|
299
|
+
continue;
|
|
300
|
+
}
|
|
301
|
+
const assetPath = path.resolve(assetsDirectory, entryName);
|
|
302
|
+
assert(
|
|
303
|
+
assetPath.startsWith(`${assetsDirectory}${path.sep}`),
|
|
304
|
+
`SB3 archive entry escapes the assets directory: ${JSON.stringify(entryName)}`,
|
|
305
|
+
);
|
|
306
|
+
await mkdir(path.dirname(assetPath), {recursive: true});
|
|
307
|
+
await writeFile(assetPath, contents);
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
for (const extension of decodedExtensionSources) {
|
|
311
|
+
await writeFile(path.join(temporaryDirectory, extension.path), extension.source);
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
const sourceManifest = {
|
|
315
|
+
formatVersion: sourceFormatVersion,
|
|
316
|
+
project: 'project.source.json',
|
|
317
|
+
embeddedExtensions: 'embedded-extensions.json',
|
|
318
|
+
assetsDirectory: 'assets',
|
|
319
|
+
archiveEntries: archiveEntries.map(([entryName]) => entryName),
|
|
320
|
+
};
|
|
321
|
+
await Promise.all([
|
|
322
|
+
writeFile(
|
|
323
|
+
path.join(temporaryDirectory, 'project.source.json'),
|
|
324
|
+
`${JSON.stringify(project, null, 2)}\n`,
|
|
325
|
+
),
|
|
326
|
+
writeFile(
|
|
327
|
+
path.join(temporaryDirectory, 'embedded-extensions.json'),
|
|
328
|
+
`${JSON.stringify({formatVersion: sourceFormatVersion, extensions: embeddedExtensions}, null, 2)}\n`,
|
|
329
|
+
),
|
|
330
|
+
writeFile(
|
|
331
|
+
path.join(temporaryDirectory, 'sb3-source.json'),
|
|
332
|
+
`${JSON.stringify(sourceManifest, null, 2)}\n`,
|
|
333
|
+
),
|
|
334
|
+
]);
|
|
335
|
+
decision = await authorizeOutputReplacement({
|
|
336
|
+
candidateDirectory: temporaryDirectory,
|
|
337
|
+
confirmReplace,
|
|
338
|
+
discardLocalChanges,
|
|
339
|
+
outputDirectory: resolvedOutputDirectory,
|
|
340
|
+
yes,
|
|
341
|
+
});
|
|
342
|
+
if (decision.action === 'unchanged') {
|
|
343
|
+
await rm(temporaryDirectory, {recursive: true, force: true});
|
|
344
|
+
} else {
|
|
345
|
+
if (decision.action === 'replace') {
|
|
346
|
+
await revalidateOutputReplacement({
|
|
347
|
+
candidateDirectory: temporaryDirectory,
|
|
348
|
+
decision,
|
|
349
|
+
discardLocalChanges,
|
|
350
|
+
outputDirectory: resolvedOutputDirectory,
|
|
351
|
+
});
|
|
352
|
+
}
|
|
353
|
+
({rollbackCleanupWarning} = await replaceDirectoryTransactionally(
|
|
354
|
+
temporaryDirectory,
|
|
355
|
+
resolvedOutputDirectory,
|
|
356
|
+
));
|
|
357
|
+
}
|
|
358
|
+
} catch (error) {
|
|
359
|
+
await rm(temporaryDirectory, {recursive: true, force: true});
|
|
360
|
+
throw error;
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
return {
|
|
364
|
+
archiveEntryCount: archiveEntries.length,
|
|
365
|
+
assetCount: archiveEntries.filter(
|
|
366
|
+
([entryName]) => entryName !== 'project.json' && !entryName.endsWith('/'),
|
|
367
|
+
).length,
|
|
368
|
+
embeddedExtensionCount: embeddedExtensions.length,
|
|
369
|
+
changed: decision.action !== 'unchanged',
|
|
370
|
+
differenceCounts: decision.comparison
|
|
371
|
+
? {
|
|
372
|
+
added: decision.comparison.differences.added.length,
|
|
373
|
+
modified: decision.comparison.differences.modified.length,
|
|
374
|
+
removed: decision.comparison.differences.removed.length,
|
|
375
|
+
}
|
|
376
|
+
: null,
|
|
377
|
+
inputPath: resolvedInputPath,
|
|
378
|
+
outputDirectory: resolvedOutputDirectory,
|
|
379
|
+
rollbackCleanupWarning,
|
|
380
|
+
};
|
|
381
|
+
}
|
package/src/index.js
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MPL-2.0
|
|
2
|
+
|
|
3
|
+
export {validateArchiveEntryName} from './archive.js';
|
|
4
|
+
export {buildSb3} from './build.js';
|
|
5
|
+
export {packageName, packageVersion} from './constants.js';
|
|
6
|
+
export {
|
|
7
|
+
extensionHeaderId,
|
|
8
|
+
extensionIntegrity,
|
|
9
|
+
validateExtensionSourceMetadata,
|
|
10
|
+
validateManagedExtensionContents,
|
|
11
|
+
} from './extension-dependencies.js';
|
|
12
|
+
export {
|
|
13
|
+
migrateExtensionId,
|
|
14
|
+
planExtensionIdMigration,
|
|
15
|
+
validateNewExtensionId,
|
|
16
|
+
} from './extension-id-migration.js';
|
|
17
|
+
export {
|
|
18
|
+
defaultExtensionArtifactSizeLimit,
|
|
19
|
+
extensionStatus,
|
|
20
|
+
syncExtensions,
|
|
21
|
+
updateExtensions,
|
|
22
|
+
} from './extension-sync.js';
|
|
23
|
+
export {decodeExtensionDataUrl, importSb3} from './import.js';
|
|
24
|
+
export {
|
|
25
|
+
compareDirectories,
|
|
26
|
+
inspectGitOutputState,
|
|
27
|
+
validateOutputDirectoryPath,
|
|
28
|
+
} from './output-safety.js';
|
|
29
|
+
export {
|
|
30
|
+
createDeterministicSb3,
|
|
31
|
+
fixedZipTimestamp,
|
|
32
|
+
sourceFormatVersion,
|
|
33
|
+
validateSb3Source,
|
|
34
|
+
} from './source.js';
|