@exodus/stasis-core 1.0.0-beta.2 → 1.0.0-beta.4
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 +1 -1
- package/bin/stasis-core.js +26 -30
- package/package.json +9 -1
- package/src/add.js +325 -0
- package/src/artifact-util.js +318 -0
- package/src/brotli.js +4 -12
- package/src/bundle-util.js +66 -0
- package/src/bundle.js +97 -92
- package/src/config.js +47 -122
- package/src/extract.js +159 -0
- package/src/fs.js +86 -347
- package/src/hooks.js +108 -498
- package/src/loader.js +1 -3
- package/src/lockfile.js +82 -68
- package/src/prune.js +37 -152
- package/src/shard.js +60 -0
- package/src/state-util.js +4 -26
- package/src/state.js +527 -1295
- package/src/util.js +299 -178
package/src/config.js
CHANGED
|
@@ -8,37 +8,28 @@ const VALID_LOCK = new Set(['none', 'ignore', 'add', 'replace', 'frozen'])
|
|
|
8
8
|
const VALID_BUNDLE = new Set(['none', 'ignore', 'add', 'replace', 'load', 'frozen'])
|
|
9
9
|
const VALID_FS = new Set(['sync', 'async'])
|
|
10
10
|
|
|
11
|
-
// The defaults Config applies when neither env nor options specify a value.
|
|
12
|
-
// Exported so callers (plugins.js error messages) can reference the same source of
|
|
13
|
-
// truth instead of hardcoding the literal -- a default drift then surfaces at one
|
|
14
|
-
// place, not silently in a user-facing message.
|
|
15
11
|
export const DEFAULT_LOCK = 'add'
|
|
16
12
|
export const DEFAULT_BUNDLE = 'none'
|
|
17
13
|
export const DEFAULT_SCOPE = 'full'
|
|
18
14
|
|
|
19
|
-
// Strict
|
|
20
|
-
// ('no', 'off', ...) throws -- a truthiness parse would read those as *enabling* the
|
|
21
|
-
// toggle, and a misconfigured env var should fail loudly, not silently flip a feature on.
|
|
15
|
+
// Strict, not truthy: a truthiness parse would read 'no'/'off' as *enabling* the toggle.
|
|
22
16
|
const envBool = (name, value) => {
|
|
23
17
|
if (value === '' || value === '0' || value === 'false') return false
|
|
24
18
|
if (value === '1' || value === 'true') return true
|
|
25
19
|
throw new RangeError(`${name} must be ''/'0'/'false' or '1'/'true' (got '${value}')`)
|
|
26
20
|
}
|
|
27
21
|
|
|
28
|
-
// EXODUS_STASIS_RESOURCES is a comma-separated extension list;
|
|
29
|
-
// empties so '' and ' png , svg ' normalize predictably (parseResourcesOption then
|
|
30
|
-
// validates each entry). An empty/unset env var means "no allowlist".
|
|
22
|
+
// EXODUS_STASIS_RESOURCES is a comma-separated extension list; empty/unset means "no allowlist".
|
|
31
23
|
const envList = (value) => value.split(',').map((s) => s.trim()).filter(Boolean)
|
|
32
24
|
|
|
33
|
-
const OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'resources', 'childProcess']
|
|
25
|
+
const OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'resources', 'childProcess', 'packageJSON']
|
|
34
26
|
|
|
35
|
-
// Plugins
|
|
36
|
-
// since constructing State has side effects. Mirror Config's per-field validation.
|
|
27
|
+
// Plugins validate the same options without constructing a Config (which has side effects).
|
|
37
28
|
export function validatePluginOptions(label, options) {
|
|
38
29
|
const rest = { ...options }
|
|
39
30
|
for (const key of OPTION_KEYS) delete rest[key]
|
|
40
31
|
assert.equal(Object.keys(rest).length, 0, `Unknown ${label} options: ${Object.keys(rest).join(', ')}`)
|
|
41
|
-
const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess } = options
|
|
32
|
+
const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, packageJSON } = options
|
|
42
33
|
if (scope !== undefined) assert.ok(VALID_SCOPE.has(scope), `Invalid scope: ${scope}`)
|
|
43
34
|
if (lock !== undefined) assert.ok(VALID_LOCK.has(lock), `Invalid lock: ${lock}`)
|
|
44
35
|
if (bundle !== undefined) assert.ok(VALID_BUNDLE.has(bundle), `Invalid bundle: ${bundle}`)
|
|
@@ -46,18 +37,14 @@ export function validatePluginOptions(label, options) {
|
|
|
46
37
|
if (resourcesBundleFile !== undefined) assert.equal(typeof resourcesBundleFile, 'string', 'resourcesBundleFile must be a string')
|
|
47
38
|
if (debug !== undefined) assert.equal(typeof debug, 'boolean', 'debug must be a boolean')
|
|
48
39
|
if (childProcess !== undefined) assert.equal(typeof childProcess, 'boolean', 'childProcess must be a boolean')
|
|
49
|
-
|
|
50
|
-
// malformed extensions, or a code extension (those are always tracked, never resources).
|
|
40
|
+
if (packageJSON !== undefined) assert.equal(typeof packageJSON, 'boolean', 'packageJSON must be a boolean')
|
|
51
41
|
if (resources !== undefined) parseResourcesOption(label, resources)
|
|
52
42
|
}
|
|
53
43
|
|
|
54
|
-
//
|
|
55
|
-
// is authoritative. Any options the plugin was given must agree with it.
|
|
44
|
+
// The active Config is authoritative; options a plugin was given must agree with it.
|
|
56
45
|
export function assertOptionsMatchConfig(config, options) {
|
|
57
|
-
const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, childProcess } = options
|
|
58
|
-
// `resources` is
|
|
59
|
-
// which assert.equal can't express) and is coordinated explicitly in resolvePluginState
|
|
60
|
-
// before this runs -- don't "fix" the omission with assert.equal(config.resources, ...).
|
|
46
|
+
const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, childProcess, packageJSON } = options
|
|
47
|
+
// `resources` is deliberately NOT checked here: it's a Set, coordinated in resolvePluginState.
|
|
61
48
|
try {
|
|
62
49
|
if (scope !== undefined) assert.equal(config.scope, scope)
|
|
63
50
|
if (lock !== undefined) assert.equal(config.lock, lock)
|
|
@@ -66,10 +53,8 @@ export function assertOptionsMatchConfig(config, options) {
|
|
|
66
53
|
if (resourcesBundleFile !== undefined) assert.equal(config.resourcesBundleFile, resourcesBundleFile)
|
|
67
54
|
if (debug !== undefined) assert.equal(config.debug, debug)
|
|
68
55
|
if (childProcess !== undefined) assert.equal(config.childProcess, childProcess)
|
|
56
|
+
if (packageJSON !== undefined) assert.equal(config.packageJSON, packageJSON)
|
|
69
57
|
} catch (cause) {
|
|
70
|
-
// Re-throw with the underlying assertion message folded into the top-level
|
|
71
|
-
// text -- a plugin author hitting this gets the offending field's name and
|
|
72
|
-
// expected/actual values without having to inspect err.cause.
|
|
73
58
|
throw new Error(`Plugin options conflict with active stasis state: ${cause.message}`, { cause })
|
|
74
59
|
}
|
|
75
60
|
}
|
|
@@ -86,22 +71,16 @@ export class Config {
|
|
|
86
71
|
#resources
|
|
87
72
|
#debug
|
|
88
73
|
#childProcess
|
|
74
|
+
#packageJSON
|
|
89
75
|
#shardSignalFlush
|
|
90
76
|
#fs
|
|
91
77
|
#brotliQuality
|
|
92
78
|
|
|
93
|
-
//
|
|
94
|
-
// resources/childProcess/fs/brotliQuality).
|
|
95
|
-
// Env vars take effect at construction time; if both env and an option are set they must
|
|
96
|
-
// agree. Likewise, any explicit constructor option is treated as authoritative: a later
|
|
97
|
-
// `loadConfig` call (which reads stasis.config.json) must agree with it -- the alternative
|
|
98
|
-
// (silently overwriting `--scope=full` with the file's `"scope":"node_modules"`)
|
|
99
|
-
// was a footgun the CLI couldn't detect, since the flag was happily accepted
|
|
100
|
-
// and then quietly ignored.
|
|
79
|
+
// Env and options must agree when both are set; #explicit is kept so a later loadConfig can't override them.
|
|
101
80
|
constructor(options = {}) {
|
|
102
|
-
const { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, fs, brotliQuality, ...rest } = options
|
|
81
|
+
const { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, packageJSON, fs, brotliQuality, ...rest } = options
|
|
103
82
|
assert.equal(Object.keys(rest).length, 0, `Unknown Config options: ${Object.keys(rest).join(', ')}`)
|
|
104
|
-
this.#explicit = { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, fs, brotliQuality }
|
|
83
|
+
this.#explicit = { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, packageJSON, fs, brotliQuality }
|
|
105
84
|
|
|
106
85
|
this.#env = {
|
|
107
86
|
scope: process.env.EXODUS_STASIS_SCOPE || undefined,
|
|
@@ -113,6 +92,7 @@ export class Config {
|
|
|
113
92
|
debug: process.env.EXODUS_STASIS_DEBUG || undefined,
|
|
114
93
|
resources: process.env.EXODUS_STASIS_RESOURCES || undefined,
|
|
115
94
|
childProcess: process.env.EXODUS_STASIS_CHILD_PROCESS || undefined,
|
|
95
|
+
packageJSON: process.env.EXODUS_STASIS_PACKAGE_JSON || undefined,
|
|
116
96
|
shardSignalFlush: process.env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH || undefined,
|
|
117
97
|
fs: process.env.EXODUS_STASIS_FS || undefined,
|
|
118
98
|
brotliQuality: process.env.EXODUS_STASIS_BROTLI_QUALITY || undefined,
|
|
@@ -137,13 +117,14 @@ export class Config {
|
|
|
137
117
|
if (this.#env.childProcess !== undefined && childProcess !== undefined) {
|
|
138
118
|
assert.equal(envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess), childProcess)
|
|
139
119
|
}
|
|
120
|
+
if (this.#env.packageJSON !== undefined && packageJSON !== undefined) {
|
|
121
|
+
assert.equal(envBool('EXODUS_STASIS_PACKAGE_JSON', this.#env.packageJSON), packageJSON)
|
|
122
|
+
}
|
|
140
123
|
if (this.#env.fs !== undefined && fs !== undefined) assert.equal(this.#env.fs, fs)
|
|
141
124
|
if (this.#env.brotliQuality !== undefined && brotliQuality !== undefined) {
|
|
142
125
|
assert.equal(parseBrotliQuality('EXODUS_STASIS_BROTLI_QUALITY', this.#env.brotliQuality), brotliQuality)
|
|
143
126
|
}
|
|
144
|
-
// Compare parsed sets, not
|
|
145
|
-
// same allowlist. An empty/unset env var is "no env opinion" (handled by `||
|
|
146
|
-
// undefined` above), so this only fires on two genuinely different non-empty lists.
|
|
127
|
+
// Compare parsed sets, not raw strings: ['png','svg'] and 'svg,png' are the same allowlist.
|
|
147
128
|
if (this.#env.resources !== undefined && resources !== undefined) {
|
|
148
129
|
assert.ok(
|
|
149
130
|
extSetsEqual(parseResourcesOption('env', envList(this.#env.resources)), parseResourcesOption('options', resources)),
|
|
@@ -162,19 +143,15 @@ export class Config {
|
|
|
162
143
|
this.#resourcesBundleFile = this.#env.resourcesBundleFile || resourcesBundleFile || undefined
|
|
163
144
|
this.#debug = this.#env.debug !== undefined ? envBool('EXODUS_STASIS_DEBUG', this.#env.debug) : (debug ?? false)
|
|
164
145
|
this.#childProcess = this.#env.childProcess !== undefined ? envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess) : (childProcess ?? false)
|
|
165
|
-
|
|
166
|
-
// process sets for its descendants, not a user-facing knob -- see the getter.
|
|
146
|
+
this.#packageJSON = this.#env.packageJSON !== undefined ? envBool('EXODUS_STASIS_PACKAGE_JSON', this.#env.packageJSON) : (packageJSON ?? false)
|
|
167
147
|
this.#shardSignalFlush = this.#env.shardSignalFlush !== undefined
|
|
168
148
|
? envBool('EXODUS_STASIS_SHARD_SIGNAL_FLUSH', this.#env.shardSignalFlush)
|
|
169
149
|
: false
|
|
170
|
-
// env wins over the option, like scope/lock/bundle; undefined means "fs untouched" (off).
|
|
171
150
|
this.#fs = this.#env.fs || fs || undefined
|
|
172
|
-
//
|
|
151
|
+
// No `||` chaining here -- 0 is a valid quality and falsy.
|
|
173
152
|
this.#brotliQuality = this.#env.brotliQuality !== undefined
|
|
174
153
|
? parseBrotliQuality('EXODUS_STASIS_BROTLI_QUALITY', this.#env.brotliQuality)
|
|
175
154
|
: brotliQuality
|
|
176
|
-
// env wins over the option (it's the process-wide signal); parseResourcesOption
|
|
177
|
-
// normalizes both to a Set of lowercase extensions/filenames, or empty when neither set.
|
|
178
155
|
this.#resources = parseResourcesOption(
|
|
179
156
|
'resources',
|
|
180
157
|
this.#env.resources !== undefined ? envList(this.#env.resources) : resources
|
|
@@ -183,24 +160,19 @@ export class Config {
|
|
|
183
160
|
this.#checkInvariants()
|
|
184
161
|
}
|
|
185
162
|
|
|
186
|
-
// Per-field validation + cross-field invariants. Constructor (options path) and
|
|
187
|
-
// loadConfig (disk path) both call this so the rules live in one place.
|
|
188
163
|
#checkInvariants() {
|
|
189
164
|
assert.ok(VALID_SCOPE.has(this.#scope), `Invalid scope: ${this.#scope}`)
|
|
190
165
|
assert.ok(VALID_LOCK.has(this.#lock), `Invalid lock: ${this.#lock}`)
|
|
191
166
|
assert.ok(VALID_BUNDLE.has(this.#bundle), `Invalid bundle: ${this.#bundle}`)
|
|
192
167
|
assert.equal(typeof this.#debug, 'boolean', 'debug must be a boolean')
|
|
193
168
|
assert.equal(typeof this.#childProcess, 'boolean', 'childProcess must be a boolean')
|
|
194
|
-
|
|
195
|
-
// (the same stasis.config.json serves capture and load runs).
|
|
169
|
+
assert.equal(typeof this.#packageJSON, 'boolean', 'packageJSON must be a boolean')
|
|
196
170
|
if (this.#brotliQuality !== undefined && !isBrotliQuality(this.#brotliQuality)) {
|
|
197
171
|
throw new RangeError(`brotliQuality must be an integer 0..11 (got ${JSON.stringify(this.#brotliQuality)})`)
|
|
198
172
|
}
|
|
199
173
|
if (this.#fs !== undefined) {
|
|
200
174
|
assert.ok(VALID_FS.has(this.#fs), `Invalid fs: ${this.#fs}`)
|
|
201
|
-
// --fs
|
|
202
|
-
// from it (load); with any other bundle mode it has nothing to record into or read from.
|
|
203
|
-
// Mirrors the CLI's "--fs requires --bundle=(add|replace|load)" guard.
|
|
175
|
+
// --fs captures into the bundle (add/replace) or serves from it (load); other modes have nothing to do.
|
|
204
176
|
if (this.#bundle !== 'add' && this.#bundle !== 'replace' && this.#bundle !== 'load') {
|
|
205
177
|
throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${this.#bundle}')`)
|
|
206
178
|
}
|
|
@@ -208,26 +180,18 @@ export class Config {
|
|
|
208
180
|
if (this.#bundleFile !== undefined) assert.equal(typeof this.#bundleFile, 'string', 'bundleFile must be a string')
|
|
209
181
|
if (this.#lockFile !== undefined) {
|
|
210
182
|
assert.equal(typeof this.#lockFile, 'string', 'lockFile must be a string')
|
|
211
|
-
// lockFile is only meaningful when there IS a lockfile. Lock modes that opt out
|
|
212
|
-
// (none / ignore) would silently ignore the path -- catch the misconfig explicitly.
|
|
213
183
|
if (this.#lock === 'none' || this.#lock === 'ignore') {
|
|
214
184
|
throw new RangeError(`lockFile requires an active lock mode (got lock='${this.#lock}')`)
|
|
215
185
|
}
|
|
216
186
|
}
|
|
217
187
|
if (this.#resourcesBundleFile !== undefined) {
|
|
218
188
|
assert.equal(typeof this.#resourcesBundleFile, 'string', 'resourcesBundleFile must be a string')
|
|
219
|
-
// The split is only meaningful when there IS a bundle to split. With bundle=none / ignore the
|
|
220
|
-
// option would be silently inert -- catch the misconfiguration explicitly instead.
|
|
221
189
|
if (this.#bundle === 'none' || this.#bundle === 'ignore') {
|
|
222
190
|
throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${this.#bundle}')`)
|
|
223
191
|
}
|
|
224
192
|
}
|
|
225
193
|
|
|
226
|
-
//
|
|
227
|
-
// resourcesBundleFile) must each name a distinct on-disk file. Canonicalize via
|
|
228
|
-
// resolve() + realpathSync so './x.br' vs 'x.br', and two symlinks to the same
|
|
229
|
-
// inode, both compare equal -- a raw string compare would let `./out/x.br` and
|
|
230
|
-
// `out/x.br` slip past and the second writer would silently clobber the first.
|
|
194
|
+
// Write targets must be distinct: canonicalize so './x.br' vs 'x.br' and symlinks to one inode compare equal.
|
|
231
195
|
const claimed = new Map()
|
|
232
196
|
for (const [label, value] of [
|
|
233
197
|
['lockFile', this.#lockFile],
|
|
@@ -242,23 +206,12 @@ export class Config {
|
|
|
242
206
|
claimed.set(canonical, label)
|
|
243
207
|
}
|
|
244
208
|
|
|
245
|
-
// bundle=load needs a trust root
|
|
246
|
-
// the lockfile and we cross-check it on load; otherwise the bundle is itself
|
|
247
|
-
// authoritative -- lock=none with no lockfile on disk, or lock=ignore with a lockfile
|
|
248
|
-
// deliberately bypassed.
|
|
249
|
-
// WARNING: the lockfile attests source bytes, entries, module identity, and
|
|
250
|
-
// (when it records them) resolutions and loader formats. Lockfiles predating
|
|
251
|
-
// a given attestation cover only what they recorded (bytes at minimum).
|
|
209
|
+
// bundle=load needs a trust root: frozen pins each file's sha512, else the bundle itself is it (none/ignore).
|
|
252
210
|
if (this.#bundle === 'load' && this.#lock !== 'frozen' && this.#lock !== 'none' && this.#lock !== 'ignore') {
|
|
253
211
|
throw new RangeError('bundle=load is incompatible with lock=(add|replace)')
|
|
254
212
|
}
|
|
255
213
|
|
|
256
|
-
// bundle=frozen
|
|
257
|
-
// bundle's bytes, it reads each file from disk and verifies it against the bundle's
|
|
258
|
-
// own recorded bytes/resolutions/formats (the bundle is itself the trust root, so it
|
|
259
|
-
// needs no sibling lockfile -- it "operates as a lockfile"). It composes with any lock
|
|
260
|
-
// mode, and (being a real bundle) satisfies the "needs a lockfile or a bundle" rule
|
|
261
|
-
// below -- which only rejects leaving both unset.
|
|
214
|
+
// bundle=frozen deliberately constrains no lock mode: it verifies disk against the bundle, its own trust root.
|
|
262
215
|
if (this.#lock === 'none' && this.#bundle === 'none') {
|
|
263
216
|
throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
|
|
264
217
|
}
|
|
@@ -273,6 +226,7 @@ export class Config {
|
|
|
273
226
|
resourcesBundleFile = this.#resourcesBundleFile,
|
|
274
227
|
debug = this.#debug,
|
|
275
228
|
childProcess = this.#childProcess,
|
|
229
|
+
packageJSON = this.#packageJSON,
|
|
276
230
|
fs = this.#fs,
|
|
277
231
|
brotliQuality = this.#brotliQuality,
|
|
278
232
|
resources,
|
|
@@ -282,13 +236,12 @@ export class Config {
|
|
|
282
236
|
this.#scope = scope
|
|
283
237
|
this.#lock = lock
|
|
284
238
|
this.#bundle = bundle
|
|
285
|
-
//
|
|
286
|
-
// everywhere downstream (State consumes bundleFile truthily), but #checkInvariants would
|
|
287
|
-
// otherwise resolve('') -> cwd and claim it as a write target.
|
|
239
|
+
// '' -> undefined like the constructor: otherwise canonicalizePath('') claims cwd as a write target.
|
|
288
240
|
this.#bundleFile = bundleFile || undefined
|
|
289
241
|
this.#resourcesBundleFile = resourcesBundleFile || undefined
|
|
290
242
|
this.#debug = debug
|
|
291
243
|
this.#childProcess = childProcess
|
|
244
|
+
this.#packageJSON = packageJSON
|
|
292
245
|
this.#fs = fs
|
|
293
246
|
this.#brotliQuality = brotliQuality
|
|
294
247
|
if (resources !== undefined) this.#resources = parseResourcesOption('stasis.config.json', resources)
|
|
@@ -302,6 +255,7 @@ export class Config {
|
|
|
302
255
|
if (this.#env.resourcesBundleFile !== undefined) assert.equal(this.#resourcesBundleFile, this.#env.resourcesBundleFile)
|
|
303
256
|
if (this.#env.debug !== undefined) assert.equal(this.#debug, envBool('EXODUS_STASIS_DEBUG', this.#env.debug))
|
|
304
257
|
if (this.#env.childProcess !== undefined) assert.equal(this.#childProcess, envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess))
|
|
258
|
+
if (this.#env.packageJSON !== undefined) assert.equal(this.#packageJSON, envBool('EXODUS_STASIS_PACKAGE_JSON', this.#env.packageJSON))
|
|
305
259
|
if (this.#env.fs !== undefined) assert.equal(this.#fs, this.#env.fs)
|
|
306
260
|
if (this.#env.brotliQuality !== undefined) {
|
|
307
261
|
assert.equal(this.#brotliQuality, parseBrotliQuality('EXODUS_STASIS_BROTLI_QUALITY', this.#env.brotliQuality))
|
|
@@ -310,9 +264,7 @@ export class Config {
|
|
|
310
264
|
assert.ok(extSetsEqual(this.#resources, parseResourcesOption('env', envList(this.#env.resources))),
|
|
311
265
|
'resources in stasis.config.json must match EXODUS_STASIS_RESOURCES')
|
|
312
266
|
}
|
|
313
|
-
// Explicit constructor options are equally authoritative: an
|
|
314
|
-
// `--scope=full` shouldn't be silently overridden by an on-disk
|
|
315
|
-
// `{"scope":"node_modules"}`. The asserts mirror the env block above.
|
|
267
|
+
// Explicit constructor options are equally authoritative: an on-disk config can't override --scope=full.
|
|
316
268
|
if (this.#explicit.scope !== undefined) assert.equal(this.#scope, this.#explicit.scope)
|
|
317
269
|
if (this.#explicit.lock !== undefined) assert.equal(this.#lock, this.#explicit.lock)
|
|
318
270
|
if (this.#explicit.bundle !== undefined) assert.equal(this.#bundle, this.#explicit.bundle)
|
|
@@ -320,6 +272,7 @@ export class Config {
|
|
|
320
272
|
if (this.#explicit.resourcesBundleFile !== undefined) assert.equal(this.#resourcesBundleFile, this.#explicit.resourcesBundleFile)
|
|
321
273
|
if (this.#explicit.debug !== undefined) assert.equal(this.#debug, this.#explicit.debug)
|
|
322
274
|
if (this.#explicit.childProcess !== undefined) assert.equal(this.#childProcess, this.#explicit.childProcess)
|
|
275
|
+
if (this.#explicit.packageJSON !== undefined) assert.equal(this.#packageJSON, this.#explicit.packageJSON)
|
|
323
276
|
if (this.#explicit.fs !== undefined) assert.equal(this.#fs, this.#explicit.fs)
|
|
324
277
|
if (this.#explicit.brotliQuality !== undefined) assert.equal(this.#brotliQuality, this.#explicit.brotliQuality)
|
|
325
278
|
if (this.#explicit.resources !== undefined) {
|
|
@@ -335,25 +288,17 @@ export class Config {
|
|
|
335
288
|
return this.#bundleFile
|
|
336
289
|
}
|
|
337
290
|
|
|
338
|
-
//
|
|
339
|
-
// discovering `stasis.lock.json` at the project root. Set via the CLI,
|
|
340
|
-
// `EXODUS_STASIS_LOCK_FILE`, or direct State construction; bundler plugins
|
|
341
|
-
// can't set it (they always share the ambient lockfile). Unset -> default
|
|
342
|
-
// discovery applies.
|
|
291
|
+
// Exact lockfile path, bypassing `stasis.lock.json` discovery; bundler plugins can't set it.
|
|
343
292
|
get lockFile() {
|
|
344
293
|
return this.#lockFile
|
|
345
294
|
}
|
|
346
295
|
|
|
347
|
-
// When set,
|
|
348
|
-
// bundle=load reads both. Unset is the default unified-bundle behavior.
|
|
296
|
+
// When set, resources go to this file and code-only to bundleFile; bundle=load reads both.
|
|
349
297
|
get resourcesBundleFile() {
|
|
350
298
|
return this.#resourcesBundleFile
|
|
351
299
|
}
|
|
352
300
|
|
|
353
|
-
//
|
|
354
|
-
// filenames that classifyExtension treats as asset payloads. Drives both the plugins'
|
|
355
|
-
// per-import classification and State's `--fs` capture, so the two share one list.
|
|
356
|
-
// Empty Set when no allowlist was configured (option or EXODUS_STASIS_RESOURCES).
|
|
301
|
+
// Set of lowercase extensions/filenames treated as asset payloads.
|
|
357
302
|
get resources() {
|
|
358
303
|
return this.#resources
|
|
359
304
|
}
|
|
@@ -362,43 +307,28 @@ export class Config {
|
|
|
362
307
|
return this.#debug
|
|
363
308
|
}
|
|
364
309
|
|
|
365
|
-
// Opt-in
|
|
366
|
-
// stasis.config.json): enable cross-process capture forwarding. A forked child (e.g. a
|
|
367
|
-
// Metro transform worker) writes a shard of what it captured into a root-owned dir, and
|
|
368
|
-
// the root merges it before writing -- so files only a child loads (a worker's babel
|
|
369
|
-
// toolchain) are attested. Off by default: the shard dir is a process-coordination channel,
|
|
370
|
-
// so it's only created when explicitly enabled. Not attested (not in `values`), like debug.
|
|
310
|
+
// Opt-in cross-process capture forwarding: a forked child writes a shard the root merges. Not attested.
|
|
371
311
|
get childProcess() {
|
|
372
312
|
return this.#childProcess
|
|
373
313
|
}
|
|
374
314
|
|
|
375
|
-
// Opt-in
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
//
|
|
381
|
-
//
|
|
382
|
-
// disposition -- the user's domain in arbitrary children) and NOT a user option: it is
|
|
383
|
-
// channel plumbing like EXODUS_STASIS_SHARD_DIR/_KEY, but parsed strictly through
|
|
384
|
-
// envBool like every other boolean toggle so '0'/'false' disable rather than enable.
|
|
385
|
-
// Not attested (not in `values`), like childProcess.
|
|
315
|
+
// Opt-in: bundle every bundled module's package.json even if the run never reached it. Not attested.
|
|
316
|
+
get packageJSON() {
|
|
317
|
+
return this.#packageJSON
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
// Env-only: a capturing child flushes its shard on SIGTERM (jest-worker force-kills Metro workers),
|
|
321
|
+
// then re-delivers the signal. Not a user option, not attested.
|
|
386
322
|
get shardSignalFlush() {
|
|
387
323
|
return this.#shardSignalFlush
|
|
388
324
|
}
|
|
389
325
|
|
|
390
|
-
//
|
|
391
|
-
// their async (callback + fs.promises) counterparts, undefined leaves fs untouched. Set via
|
|
392
|
-
// --fs / EXODUS_STASIS_FS / "fs" in stasis.config.json; the runtime loader (hooks.js) reads
|
|
393
|
-
// this on State init to decide whether (and how) to install the fs hooks. Not serialized --
|
|
394
|
-
// a how-to-run flag like debug/childProcess, not an attested property of the bundle.
|
|
326
|
+
// --fs hook mode: 'sync' patches the sync readers, 'async' both; undefined leaves fs untouched. Not serialized.
|
|
395
327
|
get fs() {
|
|
396
328
|
return this.#fs
|
|
397
329
|
}
|
|
398
330
|
|
|
399
|
-
// Brotli quality (
|
|
400
|
-
// max). State.write() forwards this to brotliOptions(). Not serialized -- a how-to-write
|
|
401
|
-
// flag like debug/fs; the bundle's decompressed content is identical at any quality.
|
|
331
|
+
// Brotli quality (0..11); undefined -> DEFAULT_BROTLI_QUALITY. Not serialized -- output decompresses identically.
|
|
402
332
|
get brotliQuality() {
|
|
403
333
|
return this.#brotliQuality
|
|
404
334
|
}
|
|
@@ -431,11 +361,7 @@ export class Config {
|
|
|
431
361
|
return this.#bundle === 'load'
|
|
432
362
|
}
|
|
433
363
|
|
|
434
|
-
// bundle=frozen:
|
|
435
|
-
// It is loaded (its bytes/resolutions/entries/modules become the attested set) but
|
|
436
|
-
// never rewritten, and every file/resolution observed from disk is checked against
|
|
437
|
-
// it. Distinct from load (which serves bytes from the bundle instead of reading disk)
|
|
438
|
-
// and from add (which loads-then-rewrites and tolerates new files).
|
|
364
|
+
// bundle=frozen: loaded, never rewritten, and disk is checked against it (load serves bytes instead).
|
|
439
365
|
get frozenBundle() {
|
|
440
366
|
return this.#bundle === 'frozen'
|
|
441
367
|
}
|
|
@@ -474,8 +400,7 @@ export class Config {
|
|
|
474
400
|
|
|
475
401
|
get json() {
|
|
476
402
|
const data = { scope: this.#scope, lock: this.#lock, bundle: this.#bundle }
|
|
477
|
-
// resources
|
|
478
|
-
// when non-empty so configs without an allowlist serialize byte-identically as before.
|
|
403
|
+
// Only serialize `resources` when non-empty, so configs without an allowlist stay byte-identical.
|
|
479
404
|
if (this.#resources.size > 0) data.resources = [...this.#resources].toSorted()
|
|
480
405
|
return JSON.stringify(data, undefined, 2) + '\n'
|
|
481
406
|
}
|
package/src/extract.js
ADDED
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
|
|
2
|
+
import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
|
|
3
|
+
import { brotliDecompressSync } from 'node:zlib'
|
|
4
|
+
|
|
5
|
+
import { Bundle } from './bundle.js'
|
|
6
|
+
import { Lockfile } from './lockfile.js'
|
|
7
|
+
import { sha512integrity } from './state-util.js'
|
|
8
|
+
import { EXECUTE_BITS, canObserveExecuteBits, moduleFileKey } from './util.js'
|
|
9
|
+
|
|
10
|
+
const FILE_LOCK = 'stasis.lock.json'
|
|
11
|
+
|
|
12
|
+
// Buffer.from silently drops invalid chars, so a tampered `resource:base64` could hash-spoof; require a fixed point.
|
|
13
|
+
function assertCanonicalBase64(content, file) {
|
|
14
|
+
const buf = Buffer.from(content, 'base64')
|
|
15
|
+
if (buf.toString('base64') !== content) {
|
|
16
|
+
throw new Error(`extract: non-canonical base64 in resource:base64 content for ${file}`)
|
|
17
|
+
}
|
|
18
|
+
return buf
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
export function lockfileFromBundle(bundle) {
|
|
22
|
+
const modules = new Map()
|
|
23
|
+
for (const [dir, { name, version, ecosystem, files }] of bundle.modules) {
|
|
24
|
+
const hashed = Object.create(null)
|
|
25
|
+
for (const [rel, content] of Object.entries(files)) {
|
|
26
|
+
// Hash the raw on-disk bytes, so decode 'resource:base64' back first.
|
|
27
|
+
const file = moduleFileKey(dir, rel)
|
|
28
|
+
const bytes = bundle.formats.get(file) === 'resource:base64'
|
|
29
|
+
? assertCanonicalBase64(content, file)
|
|
30
|
+
: content
|
|
31
|
+
hashed[rel] = sha512integrity(bytes)
|
|
32
|
+
}
|
|
33
|
+
modules.set(dir, ecosystem === undefined
|
|
34
|
+
? { name, version, files: hashed }
|
|
35
|
+
: { name, version, ecosystem, files: hashed })
|
|
36
|
+
}
|
|
37
|
+
// Carry imports+formats across, else the derived lockfile is bytes-only and a later frozen run skips those cross-checks.
|
|
38
|
+
return new Lockfile({
|
|
39
|
+
config: bundle.config,
|
|
40
|
+
entries: bundle.entries,
|
|
41
|
+
modules,
|
|
42
|
+
imports: bundle.imports,
|
|
43
|
+
formats: bundle.formats,
|
|
44
|
+
// Same file set as the bundle, so its executable list transfers as-is.
|
|
45
|
+
executable: bundle.executable,
|
|
46
|
+
})
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export function extractCommand({ cwd = process.cwd(), bundleFile, output, logLabel = 'stasis-core' } = {}) {
|
|
50
|
+
if (!bundleFile) throw new Error('extract: a bundle file is required')
|
|
51
|
+
const bundleAbs = resolve(cwd, bundleFile)
|
|
52
|
+
if (!existsSync(bundleAbs)) throw new Error(`extract: bundle file not found: ${bundleAbs}`)
|
|
53
|
+
|
|
54
|
+
let bundle
|
|
55
|
+
try {
|
|
56
|
+
bundle = Bundle.parse(brotliDecompressSync(readFileSync(bundleAbs)).toString('utf-8'))
|
|
57
|
+
} catch (cause) {
|
|
58
|
+
// Bundle.parse throws message-less asserts; wrap so the user learns which file failed.
|
|
59
|
+
throw new Error(`extract: not a valid stasis bundle: ${bundleAbs}`, { cause })
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
// v0 bundles have null metadata, so no lockfile can be derived (serialize requires name+version).
|
|
63
|
+
const withLockfile = bundle.version === Bundle.VERSION
|
|
64
|
+
|
|
65
|
+
const outDir = resolve(cwd, output ?? '.')
|
|
66
|
+
const outPrefix = outDir === sep ? outDir : `${outDir}${sep}`
|
|
67
|
+
const lockAbs = join(outDir, FILE_LOCK)
|
|
68
|
+
|
|
69
|
+
// Plan-first: every target is validated inside outDir before any write; walk modules, not the last-wins
|
|
70
|
+
// `sources` getter. Containment is lexical -- symlinks are followed, so untrusted bundles need a fresh dir (doc/extract.md).
|
|
71
|
+
const writes = []
|
|
72
|
+
const targets = new Set()
|
|
73
|
+
let executables = 0
|
|
74
|
+
for (const [dir, { files }] of bundle.modules) {
|
|
75
|
+
for (const [rel, content] of Object.entries(files)) {
|
|
76
|
+
// `key` is the per-file map key (moduleFileKey handles rel === ''); `file` below is the WRITE path and keeps
|
|
77
|
+
// the plain join, so a non-`directory` rel === '' fails the canonical-path check instead of writing at the bucket root.
|
|
78
|
+
const key = moduleFileKey(dir, rel)
|
|
79
|
+
// Skip a `directory` capture: it's a listing at the dir's own path, not a file to write (its children recreate the dir).
|
|
80
|
+
if (bundle.formats.get(key) === 'directory') continue
|
|
81
|
+
const file = dir === '.' ? rel : `${dir}/${rel}`
|
|
82
|
+
if (typeof content !== 'string') throw new Error(`extract: bundle file content is not a string: ${file}`)
|
|
83
|
+
const abs = resolve(outDir, file)
|
|
84
|
+
const relToOut = relative(outDir, abs)
|
|
85
|
+
// The `..` test is `../`-aware, NOT a bare startsWith('..') -- that would reject a legit `..foo` filename.
|
|
86
|
+
if (relToOut === '..' || relToOut.startsWith(`..${sep}`) || isAbsolute(relToOut) || !abs.startsWith(outPrefix)) {
|
|
87
|
+
throw new Error(`extract: bundle path escapes output dir: ${file}`)
|
|
88
|
+
}
|
|
89
|
+
// A non-canonical path changes under the resolve+relative round-trip; writing it desyncs tree from lockfile.
|
|
90
|
+
if (relToOut !== file) throw new Error(`extract: non-canonical bundle path: ${file}`)
|
|
91
|
+
if (targets.has(abs)) throw new Error(`extract: duplicate bundle path: ${file}`)
|
|
92
|
+
if (withLockfile && abs === lockAbs) {
|
|
93
|
+
throw new Error(`extract: bundle contains ${FILE_LOCK}, which would collide with the derived lockfile`)
|
|
94
|
+
}
|
|
95
|
+
targets.add(abs)
|
|
96
|
+
// Executability rides the plan tuple, so the chmod can only ever reach a file we actually wrote.
|
|
97
|
+
const exec = bundle.executable.has(key)
|
|
98
|
+
if (exec) executables += 1
|
|
99
|
+
const data = bundle.formats.get(key) === 'resource:base64'
|
|
100
|
+
? assertCanonicalBase64(content, file)
|
|
101
|
+
: content
|
|
102
|
+
writes.push([abs, data, exec])
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
// A planned file must not also be a parent directory of another, else the writes throw halfway through.
|
|
106
|
+
for (const [abs] of writes) {
|
|
107
|
+
for (let d = dirname(abs); d.length > outDir.length; d = dirname(d)) {
|
|
108
|
+
if (targets.has(d)) {
|
|
109
|
+
throw new Error(`extract: bundle path used as both file and directory: ${relative(outDir, d)}`)
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
const lockText = withLockfile ? lockfileFromBundle(bundle).serialize() : null
|
|
114
|
+
|
|
115
|
+
// Only the execute bit is attested, so only it is touched -- rw bits stay as written (never widen a 0600 target)
|
|
116
|
+
// and setuid/setgid/sticky are cleared. Applied to every written file; skipped for v0, which attests no modes.
|
|
117
|
+
const withModes = withLockfile && canObserveExecuteBits()
|
|
118
|
+
let chmodFailures = 0
|
|
119
|
+
const applyMode = (abs, exec) => {
|
|
120
|
+
let stats
|
|
121
|
+
try {
|
|
122
|
+
stats = lstatSync(abs)
|
|
123
|
+
} catch {
|
|
124
|
+
chmodFailures += 1
|
|
125
|
+
return
|
|
126
|
+
}
|
|
127
|
+
// Never chmod through a symlink: +x on a link's target could make an arbitrary file outside outDir runnable.
|
|
128
|
+
if (stats.isSymbolicLink()) return
|
|
129
|
+
const perms = stats.mode & 0o7777
|
|
130
|
+
const rwx = perms & 0o777
|
|
131
|
+
// Execute wherever readable, with owner-execute as a floor so an aggressive umask can't defeat it.
|
|
132
|
+
const want = exec ? rwx | ((rwx & 0o444) >> 2) | 0o100 : rwx & ~EXECUTE_BITS
|
|
133
|
+
if (want === perms) return
|
|
134
|
+
// Tolerated per file: a mode-less filesystem (vfat/exFAT/CIFS) accepts the write and rejects the chmod.
|
|
135
|
+
try {
|
|
136
|
+
chmodSync(abs, want)
|
|
137
|
+
} catch {
|
|
138
|
+
chmodFailures += 1
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
for (const [abs, content, exec] of writes) {
|
|
143
|
+
mkdirSync(dirname(abs), { recursive: true })
|
|
144
|
+
writeFileSync(abs, content)
|
|
145
|
+
if (withModes) applyMode(abs, exec)
|
|
146
|
+
}
|
|
147
|
+
mkdirSync(outDir, { recursive: true }) // for an empty bundle, where no write created it
|
|
148
|
+
if (withLockfile) writeFileSync(lockAbs, lockText)
|
|
149
|
+
|
|
150
|
+
const execNote = executables > 0 ? ` (${executables} executable)` : ''
|
|
151
|
+
console.warn(`[${logLabel}] Extracted ${writes.length} file(s)${execNote}${withLockfile ? ` and ${FILE_LOCK}` : ''} to ${outDir}`)
|
|
152
|
+
if (chmodFailures > 0) {
|
|
153
|
+
console.warn(`[${logLabel}] Warning: could not set file modes on ${chmodFailures} file(s) (the filesystem may not support them); contents were written`)
|
|
154
|
+
}
|
|
155
|
+
if (!withLockfile) {
|
|
156
|
+
console.warn(`[${logLabel}] Warning: legacy v0 bundle records no package name/version, so ${FILE_LOCK} can not be restored and was not written`)
|
|
157
|
+
}
|
|
158
|
+
return { dir: outDir, files: writes.length, executable: executables }
|
|
159
|
+
}
|