@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.
@@ -0,0 +1,247 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ import {cp, lstat, mkdtemp, readFile, rm, writeFile} from 'node:fs/promises';
4
+ import path from 'node:path';
5
+
6
+ import {
7
+ buildExtensionBundles,
8
+ validateBundleId,
9
+ validateBundleName,
10
+ validateExtensionBundleConfigurations,
11
+ } from './extension-bundle.js';
12
+ import {
13
+ assertNoInterruptedRollback,
14
+ compareDirectories,
15
+ pathExists,
16
+ replaceDirectoryTransactionally,
17
+ } from './output-safety.js';
18
+ import {createDeterministicSb3, inspectSb3SourceForExtensionSync} from './source.js';
19
+
20
+ function assert(condition, message) {
21
+ if (!condition) {
22
+ throw new Error(message);
23
+ }
24
+ }
25
+
26
+ async function inspectConfigurationSource(sourceDirectory, willReplace) {
27
+ const resolvedSourceDirectory = path.resolve(sourceDirectory);
28
+ if (willReplace) {
29
+ assert(
30
+ resolvedSourceDirectory !== path.parse(resolvedSourceDirectory).root,
31
+ 'Refusing to replace a filesystem root while configuring extension bundles.',
32
+ );
33
+ assert(
34
+ !(await pathExists(path.join(resolvedSourceDirectory, '.git'))),
35
+ 'Refusing to replace a Git repository root while configuring extension bundles.',
36
+ );
37
+ }
38
+ const stats = await lstat(resolvedSourceDirectory);
39
+ assert(
40
+ stats.isDirectory() && !stats.isSymbolicLink(),
41
+ `SB3 source must be a directory, not a file or symbolic link: ${resolvedSourceDirectory}`,
42
+ );
43
+ if (willReplace) await assertNoInterruptedRollback(resolvedSourceDirectory);
44
+ return inspectSb3SourceForExtensionSync(resolvedSourceDirectory);
45
+ }
46
+
47
+ async function readExtensionManifest(source) {
48
+ const manifestPath = path.join(
49
+ source.resolvedSourceDirectory,
50
+ source.sourceManifest.embeddedExtensions,
51
+ );
52
+ return JSON.parse(await readFile(manifestPath, 'utf8'));
53
+ }
54
+
55
+ async function configurationContext({
56
+ bundleId,
57
+ bundleName,
58
+ extensionIds,
59
+ sourceDirectory,
60
+ willReplace,
61
+ }) {
62
+ validateBundleId(bundleId);
63
+ validateBundleName(bundleName);
64
+ const source = await inspectConfigurationSource(sourceDirectory, willReplace);
65
+ const extensionManifest = await readExtensionManifest(source);
66
+ const existingBundles = validateExtensionBundleConfigurations(
67
+ extensionManifest.extensionBundles,
68
+ extensionManifest.extensions,
69
+ );
70
+ assert(
71
+ !existingBundles.some((bundle) => bundle.id === bundleId),
72
+ `Extension bundle already exists: ${bundleId}`,
73
+ );
74
+ const alreadyBundled = new Set(existingBundles.flatMap((bundle) => bundle.members));
75
+ const members =
76
+ extensionIds && extensionIds.length > 0
77
+ ? [...extensionIds]
78
+ : source.extensions
79
+ .map((extension) => extension.id)
80
+ .filter((extensionId) => !alreadyBundled.has(extensionId));
81
+ const candidateManifest = structuredClone(extensionManifest);
82
+ candidateManifest.extensionBundles = [
83
+ ...existingBundles,
84
+ {id: bundleId, members, name: bundleName},
85
+ ];
86
+ const extensionBundles = validateExtensionBundleConfigurations(
87
+ candidateManifest.extensionBundles,
88
+ candidateManifest.extensions,
89
+ );
90
+ const buildPlan = buildExtensionBundles({
91
+ extensionBundles,
92
+ extensionContents: source.extensionContents,
93
+ extensions: source.extensions,
94
+ project: source.project,
95
+ });
96
+ const configuredBundle = buildPlan.bundlePlans.find((plan) => plan.bundle.id === bundleId);
97
+ return {buildPlan, candidateManifest, configuredBundle, extensionManifest, source};
98
+ }
99
+
100
+ export async function planExtensionBundle({bundleId, bundleName, extensionIds, sourceDirectory}) {
101
+ const context = await configurationContext({
102
+ bundleId,
103
+ bundleName,
104
+ extensionIds,
105
+ sourceDirectory,
106
+ willReplace: false,
107
+ });
108
+ return {
109
+ applied: false,
110
+ bundleId,
111
+ bundleName,
112
+ changed: true,
113
+ components: context.configuredBundle.components.map((component) => component.metadata),
114
+ counts: context.configuredBundle.counts,
115
+ members: [...context.configuredBundle.bundle.members],
116
+ sourceDirectory: context.source.resolvedSourceDirectory,
117
+ };
118
+ }
119
+
120
+ async function installManifestConfiguration(context, operation) {
121
+ const initialComparison = await compareDirectories(
122
+ context.source.resolvedSourceDirectory,
123
+ context.source.resolvedSourceDirectory,
124
+ );
125
+ assert(
126
+ initialComparison.identical &&
127
+ initialComparison.existingFingerprint === initialComparison.candidateFingerprint,
128
+ `SB3 source changed while its initial ${operation} state was inspected.`,
129
+ );
130
+ const parentDirectory = path.dirname(context.source.resolvedSourceDirectory);
131
+ const candidateDirectory = await mkdtemp(
132
+ path.join(parentDirectory, `.${path.basename(context.source.resolvedSourceDirectory)}.bundle-`),
133
+ );
134
+ let installed = false;
135
+ try {
136
+ await cp(context.source.resolvedSourceDirectory, candidateDirectory, {
137
+ preserveTimestamps: true,
138
+ recursive: true,
139
+ verbatimSymlinks: true,
140
+ });
141
+ await writeFile(
142
+ path.join(candidateDirectory, context.source.sourceManifest.embeddedExtensions),
143
+ `${JSON.stringify(context.candidateManifest, null, 2)}\n`,
144
+ );
145
+ await createDeterministicSb3(candidateDirectory);
146
+ const comparison = await compareDirectories(
147
+ context.source.resolvedSourceDirectory,
148
+ candidateDirectory,
149
+ );
150
+ assert(
151
+ comparison.existingFingerprint === initialComparison.existingFingerprint,
152
+ `SB3 source changed while the ${operation} candidate was prepared; refusing to replace it.`,
153
+ );
154
+ assert(!comparison.identical, `Extension bundle ${operation} produced no source changes.`);
155
+ const latestComparison = await compareDirectories(
156
+ context.source.resolvedSourceDirectory,
157
+ candidateDirectory,
158
+ );
159
+ assert(
160
+ latestComparison.existingFingerprint === comparison.existingFingerprint &&
161
+ latestComparison.candidateFingerprint === comparison.candidateFingerprint,
162
+ `SB3 source or ${operation} candidate changed during the operation; refusing to replace it.`,
163
+ );
164
+ const replacement = await replaceDirectoryTransactionally(
165
+ candidateDirectory,
166
+ context.source.resolvedSourceDirectory,
167
+ );
168
+ installed = true;
169
+ return {comparison, ...replacement};
170
+ } finally {
171
+ if (!installed) await rm(candidateDirectory, {recursive: true, force: true});
172
+ }
173
+ }
174
+
175
+ export async function bundleExtensions({
176
+ bundleId,
177
+ bundleName,
178
+ extensionIds,
179
+ sourceDirectory,
180
+ yes = false,
181
+ }) {
182
+ const context = await configurationContext({
183
+ bundleId,
184
+ bundleName,
185
+ extensionIds,
186
+ sourceDirectory,
187
+ willReplace: yes,
188
+ });
189
+ const plan = {
190
+ bundleId,
191
+ bundleName,
192
+ components: context.configuredBundle.components.map((component) => component.metadata),
193
+ counts: context.configuredBundle.counts,
194
+ members: [...context.configuredBundle.bundle.members],
195
+ sourceDirectory: context.source.resolvedSourceDirectory,
196
+ };
197
+ if (!yes) {
198
+ return {applied: false, changed: true, ...plan, rollbackCleanupWarning: null};
199
+ }
200
+ const installation = await installManifestConfiguration(context, 'configuration');
201
+ return {applied: true, changed: true, ...installation, ...plan};
202
+ }
203
+
204
+ async function unbundleContext({bundleId, sourceDirectory, willReplace}) {
205
+ validateBundleId(bundleId);
206
+ const source = await inspectConfigurationSource(sourceDirectory, willReplace);
207
+ const extensionManifest = await readExtensionManifest(source);
208
+ const extensionBundles = validateExtensionBundleConfigurations(
209
+ extensionManifest.extensionBundles,
210
+ extensionManifest.extensions,
211
+ );
212
+ const removedBundle = extensionBundles.find((bundle) => bundle.id === bundleId);
213
+ assert(removedBundle, `Extension bundle was not found: ${bundleId}`);
214
+ const candidateManifest = structuredClone(extensionManifest);
215
+ const remainingBundles = extensionBundles.filter((bundle) => bundle.id !== bundleId);
216
+ if (remainingBundles.length === 0) {
217
+ delete candidateManifest.extensionBundles;
218
+ } else {
219
+ candidateManifest.extensionBundles = remainingBundles;
220
+ }
221
+ return {candidateManifest, extensionManifest, removedBundle, source};
222
+ }
223
+
224
+ export async function planExtensionUnbundle({bundleId, sourceDirectory}) {
225
+ const context = await unbundleContext({bundleId, sourceDirectory, willReplace: false});
226
+ return {
227
+ applied: false,
228
+ bundleId,
229
+ changed: true,
230
+ members: [...context.removedBundle.members],
231
+ sourceDirectory: context.source.resolvedSourceDirectory,
232
+ };
233
+ }
234
+
235
+ export async function unbundleExtensions({bundleId, sourceDirectory, yes = false}) {
236
+ const context = await unbundleContext({bundleId, sourceDirectory, willReplace: yes});
237
+ const plan = {
238
+ bundleId,
239
+ members: [...context.removedBundle.members],
240
+ sourceDirectory: context.source.resolvedSourceDirectory,
241
+ };
242
+ if (!yes) {
243
+ return {applied: false, changed: true, ...plan, rollbackCleanupWarning: null};
244
+ }
245
+ const installation = await installManifestConfiguration(context, 'removal');
246
+ return {applied: true, changed: true, ...installation, ...plan};
247
+ }