@exodus/stasis-core 1.0.0-beta.0 → 1.0.0-beta.10

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/src/config.js CHANGED
@@ -1,296 +1,222 @@
1
1
  import assert from 'node:assert/strict'
2
2
 
3
+ import { diskHost } from './host.js'
3
4
  import { canonicalizePath } from './state-util.js'
4
- import { extSetsEqual, parseResourcesOption } from './util.js'
5
+ import { extSetsEqual, isBrotliQuality, parseBrotliQuality, parseResourcesOption } from './util.js'
5
6
 
6
- const VALID_SCOPE = new Set(['node_modules', 'full'])
7
- const VALID_LOCK = new Set(['none', 'ignore', 'add', 'replace', 'frozen'])
8
- const VALID_BUNDLE = new Set(['none', 'ignore', 'add', 'replace', 'load', 'frozen'])
9
- const VALID_FS = new Set(['sync', 'async'])
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
7
  export const DEFAULT_LOCK = 'add'
16
8
  export const DEFAULT_BUNDLE = 'none'
17
9
  export const DEFAULT_SCOPE = 'full'
18
10
 
19
- const envBool = (value) => Boolean(value && value !== '0')
11
+ // Strict, not truthy: a truthiness parse would read 'no'/'off' as *enabling* the toggle.
12
+ const envBool = (name, value) => {
13
+ if (value === '' || value === '0' || value === 'false') return false
14
+ if (value === '1' || value === 'true') return true
15
+ throw new RangeError(`${name} must be ''/'0'/'false' or '1'/'true' (got '${value}')`)
16
+ }
20
17
 
21
- // EXODUS_STASIS_RESOURCES is a comma-separated extension list; split + trim + drop
22
- // empties so '' and ' png , svg ' normalize predictably (parseResourcesOption then
23
- // validates each entry). An empty/unset env var means "no allowlist".
18
+ // EXODUS_STASIS_RESOURCES is a comma-separated extension list; empty/unset means "no allowlist".
24
19
  const envList = (value) => value.split(',').map((s) => s.trim()).filter(Boolean)
25
20
 
26
- const OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'resources', 'childProcess']
21
+ // Every option: its env var, how the env string parses (strings pass through) and, for a non-string
22
+ // option, how a `new Config()` option does. `lockFile` is flag/env-only (never from stasis.config.json).
23
+ const OPTIONS = {
24
+ scope: { env: 'EXODUS_STASIS_SCOPE', valid: new Set(['node_modules', 'full']) },
25
+ lock: { env: 'EXODUS_STASIS_LOCK', valid: new Set(['none', 'ignore', 'add', 'replace', 'frozen']) },
26
+ lockFile: { env: 'EXODUS_STASIS_LOCK_FILE', type: 'string' },
27
+ bundle: { env: 'EXODUS_STASIS_BUNDLE', valid: new Set(['none', 'ignore', 'add', 'replace', 'load', 'frozen']) },
28
+ bundleFile: { env: 'EXODUS_STASIS_BUNDLE_FILE', type: 'string' },
29
+ resourcesBundleFile: { env: 'EXODUS_STASIS_RESOURCES_BUNDLE_FILE', type: 'string' },
30
+ debug: { env: 'EXODUS_STASIS_DEBUG', parse: envBool, type: 'boolean' },
31
+ childProcess: { env: 'EXODUS_STASIS_CHILD_PROCESS', parse: envBool, type: 'boolean' },
32
+ packageJSON: { env: 'EXODUS_STASIS_PACKAGE_JSON', parse: envBool, type: 'boolean' },
33
+ fs: { env: 'EXODUS_STASIS_FS', valid: new Set(['sync', 'async']) },
34
+ brotliQuality: { env: 'EXODUS_STASIS_BROTLI_QUALITY', parse: parseBrotliQuality },
35
+ // Compared as parsed sets, not raw strings: ['png','svg'] and 'svg,png' are the same allowlist.
36
+ resources: { env: 'EXODUS_STASIS_RESOURCES', parse: (name, value) => parseResourcesOption('env', envList(value)), option: (value) => parseResourcesOption('options', value) },
37
+ }
38
+ const OPTION_KEYS = Object.keys(OPTIONS)
39
+ const CONFIG_FILE_KEYS = OPTION_KEYS.filter((key) => key !== 'lockFile')
40
+ const PLUGIN_OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'childProcess', 'packageJSON', 'resources']
41
+
42
+ const assertKnownKeys = (keys, known, what) => {
43
+ const unknown = keys.filter((key) => !known.includes(key))
44
+ assert.equal(unknown.length, 0, `Unknown ${what} options: ${unknown.join(', ')}`)
45
+ }
46
+
47
+ // One option's membership/type rule; the cross-option rules live in #checkInvariants.
48
+ function assertOption(key, value) {
49
+ const { valid, type } = OPTIONS[key]
50
+ if (valid) assert.ok(valid.has(value), `Invalid ${key}: ${value}`)
51
+ else if (type) assert.equal(typeof value, type, `${key} must be a ${type}`)
52
+ }
53
+
54
+ // Equal for the option's type: `resources` is a Set.
55
+ const assertSame = (key, actual, expected, message) => {
56
+ if (key === 'resources') assert.ok(extSetsEqual(actual, expected), message)
57
+ else assert.equal(actual, expected)
58
+ }
27
59
 
28
- // Plugins accept the same options as Config but want to validate without constructing one,
29
- // since constructing State has side effects. Mirror Config's per-field validation.
60
+ // Plugins validate the same options without constructing a Config (which has side effects).
30
61
  export function validatePluginOptions(label, options) {
31
- const rest = { ...options }
32
- for (const key of OPTION_KEYS) delete rest[key]
33
- assert.equal(Object.keys(rest).length, 0, `Unknown ${label} options: ${Object.keys(rest).join(', ')}`)
34
- const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess } = options
35
- if (scope !== undefined) assert.ok(VALID_SCOPE.has(scope), `Invalid scope: ${scope}`)
36
- if (lock !== undefined) assert.ok(VALID_LOCK.has(lock), `Invalid lock: ${lock}`)
37
- if (bundle !== undefined) assert.ok(VALID_BUNDLE.has(bundle), `Invalid bundle: ${bundle}`)
38
- if (bundleFile !== undefined) assert.equal(typeof bundleFile, 'string', 'bundleFile must be a string')
39
- if (resourcesBundleFile !== undefined) assert.equal(typeof resourcesBundleFile, 'string', 'resourcesBundleFile must be a string')
40
- if (debug !== undefined) assert.equal(typeof debug, 'boolean', 'debug must be a boolean')
41
- if (childProcess !== undefined) assert.equal(typeof childProcess, 'boolean', 'childProcess must be a boolean')
42
- // parseResourcesOption is the validator: it throws on a non-array, non-string entries,
43
- // malformed extensions, or a code extension (those are always tracked, never resources).
44
- if (resources !== undefined) parseResourcesOption(label, resources)
62
+ assertKnownKeys(Object.keys(options), PLUGIN_OPTION_KEYS, label)
63
+ for (const key of PLUGIN_OPTION_KEYS) {
64
+ if (options[key] === undefined) continue
65
+ if (key === 'resources') parseResourcesOption(label, options.resources)
66
+ else assertOption(key, options[key])
67
+ }
45
68
  }
46
69
 
47
- // When a plugin runs against a State that already exists (preload path), the active Config
48
- // is authoritative. Any options the plugin was given must agree with it.
70
+ // The active Config is authoritative; options a plugin was given must agree with it.
49
71
  export function assertOptionsMatchConfig(config, options) {
50
- const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, childProcess } = options
51
- // `resources` is intentionally NOT cross-checked here: it's a Set (needs set-equality,
52
- // which assert.equal can't express) and is coordinated explicitly in resolvePluginState
53
- // before this runs -- don't "fix" the omission with assert.equal(config.resources, ...).
54
72
  try {
55
- if (scope !== undefined) assert.equal(config.scope, scope)
56
- if (lock !== undefined) assert.equal(config.lock, lock)
57
- if (bundle !== undefined) assert.equal(config.bundleMode, bundle)
58
- if (bundleFile !== undefined) assert.equal(config.bundleFile, bundleFile)
59
- if (resourcesBundleFile !== undefined) assert.equal(config.resourcesBundleFile, resourcesBundleFile)
60
- if (debug !== undefined) assert.equal(config.debug, debug)
61
- if (childProcess !== undefined) assert.equal(config.childProcess, childProcess)
73
+ // `resources` is deliberately NOT checked here: it's a Set, coordinated in resolvePluginState.
74
+ for (const key of PLUGIN_OPTION_KEYS) {
75
+ if (key !== 'resources' && options[key] !== undefined) assert.equal(config[key === 'bundle' ? 'bundleMode' : key], options[key])
76
+ }
62
77
  } catch (cause) {
63
- // Re-throw with the underlying assertion message folded into the top-level
64
- // text -- a plugin author hitting this gets the offending field's name and
65
- // expected/actual values without having to inspect err.cause.
66
78
  throw new Error(`Plugin options conflict with active stasis state: ${cause.message}`, { cause })
67
79
  }
68
80
  }
69
81
 
70
82
  export class Config {
71
83
  #env
84
+ #host
72
85
  #explicit
73
- #scope
74
- #lock
75
- #lockFile
76
- #bundle
77
- #bundleFile
78
- #resourcesBundleFile
79
- #resources
80
- #debug
81
- #childProcess
82
- #fs
83
-
84
- // Options match the CLI flags (scope/lock/lockFile/bundle/bundleFile/resourcesBundleFile/debug/
85
- // resources/childProcess/fs).
86
- // Env vars take effect at construction time; if both env and an option are set they must
87
- // agree. Likewise, any explicit constructor option is treated as authoritative: a later
88
- // `loadConfig` call (which reads stasis.config.json) must agree with it -- the alternative
89
- // (silently overwriting `--scope=full` with the file's `"scope":"node_modules"`)
90
- // was a footgun the CLI couldn't detect, since the flag was happily accepted
91
- // and then quietly ignored.
86
+ #opts
87
+ #shardSignalFlush
88
+
89
+ // Env and options must agree when both are set; #explicit is kept so a later loadConfig can't override them.
92
90
  constructor(options = {}) {
93
- const { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, fs, ...rest } = options
94
- assert.equal(Object.keys(rest).length, 0, `Unknown Config options: ${Object.keys(rest).join(', ')}`)
95
- this.#explicit = { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, fs }
96
-
97
- this.#env = {
98
- scope: process.env.EXODUS_STASIS_SCOPE || undefined,
99
- lock: process.env.EXODUS_STASIS_LOCK || undefined,
100
- lockFile: process.env.EXODUS_STASIS_LOCK_FILE || undefined,
101
- bundle: process.env.EXODUS_STASIS_BUNDLE || undefined,
102
- bundleFile: process.env.EXODUS_STASIS_BUNDLE_FILE || undefined,
103
- resourcesBundleFile: process.env.EXODUS_STASIS_RESOURCES_BUNDLE_FILE || undefined,
104
- debug: process.env.EXODUS_STASIS_DEBUG || undefined,
105
- resources: process.env.EXODUS_STASIS_RESOURCES || undefined,
106
- childProcess: process.env.EXODUS_STASIS_CHILD_PROCESS || undefined,
107
- fs: process.env.EXODUS_STASIS_FS || undefined,
108
- }
91
+ const { env = process.env, host = diskHost, ...rest } = options
92
+ assertKnownKeys(Object.keys(rest), OPTION_KEYS, 'Config')
93
+ // An empty-string path/mode option is unset, as its resolution below treats it; #explicit must
94
+ // agree, or loadConfig would refuse a stasis.config.json for not matching a phantom override.
95
+ const explicit = Object.fromEntries(Object.entries(rest).map(([key, value]) =>
96
+ [key, value === '' && (OPTIONS[key].valid || OPTIONS[key].type === 'string') ? undefined : value]))
97
+ this.#host = host
98
+ this.#explicit = explicit
99
+ // An env var set to '' counts as unset.
100
+ this.#env = Object.fromEntries(OPTION_KEYS.map((key) => [key, env[OPTIONS[key].env] || undefined]))
109
101
 
110
102
  try {
111
- if (this.#env.scope !== undefined && scope !== undefined) assert.equal(this.#env.scope, scope)
112
- if (this.#env.lock !== undefined && lock !== undefined) assert.equal(this.#env.lock, lock)
113
- if (this.#env.lockFile !== undefined && lockFile !== undefined) {
114
- assert.equal(this.#env.lockFile, lockFile)
115
- }
116
- if (this.#env.bundle !== undefined && bundle !== undefined) assert.equal(this.#env.bundle, bundle)
117
- if (this.#env.bundleFile !== undefined && bundleFile !== undefined) {
118
- assert.equal(this.#env.bundleFile, bundleFile)
119
- }
120
- if (this.#env.resourcesBundleFile !== undefined && resourcesBundleFile !== undefined) {
121
- assert.equal(this.#env.resourcesBundleFile, resourcesBundleFile)
122
- }
123
- if (this.#env.debug !== undefined && debug !== undefined) {
124
- assert.equal(envBool(this.#env.debug), debug)
125
- }
126
- if (this.#env.childProcess !== undefined && childProcess !== undefined) {
127
- assert.equal(envBool(this.#env.childProcess), childProcess)
128
- }
129
- if (this.#env.fs !== undefined && fs !== undefined) assert.equal(this.#env.fs, fs)
130
- // Compare parsed sets, not the raw strings: ['png','svg'] and 'svg,png' are the
131
- // same allowlist. An empty/unset env var is "no env opinion" (handled by `||
132
- // undefined` above), so this only fires on two genuinely different non-empty lists.
133
- if (this.#env.resources !== undefined && resources !== undefined) {
134
- assert.ok(
135
- extSetsEqual(parseResourcesOption('env', envList(this.#env.resources)), parseResourcesOption('options', resources)),
136
- 'resources option does not match EXODUS_STASIS_RESOURCES'
137
- )
103
+ for (const key of OPTION_KEYS) {
104
+ if (this.#env[key] !== undefined && explicit[key] !== undefined) {
105
+ assertSame(key, this.#envValue(key), this.#explicitValue(key), 'resources option does not match EXODUS_STASIS_RESOURCES')
106
+ }
138
107
  }
139
108
  } catch (cause) {
140
109
  throw new Error('Config options can not override stasis env', { cause })
141
110
  }
142
111
 
143
- this.#scope = this.#env.scope || scope || DEFAULT_SCOPE
144
- this.#lock = this.#env.lock || lock || DEFAULT_LOCK
145
- this.#lockFile = this.#env.lockFile || lockFile || undefined
146
- this.#bundle = this.#env.bundle || bundle || DEFAULT_BUNDLE
147
- this.#bundleFile = this.#env.bundleFile || bundleFile || undefined
148
- this.#resourcesBundleFile = this.#env.resourcesBundleFile || resourcesBundleFile || undefined
149
- this.#debug = this.#env.debug !== undefined ? envBool(this.#env.debug) : (debug ?? false)
150
- this.#childProcess = this.#env.childProcess !== undefined ? envBool(this.#env.childProcess) : (childProcess ?? false)
151
- // env wins over the option, like scope/lock/bundle; undefined means "fs untouched" (off).
152
- this.#fs = this.#env.fs || fs || undefined
153
- // env wins over the option (it's the process-wide signal); parseResourcesOption
154
- // normalizes both to a Set of lowercase extensions/filenames, or empty when neither set.
155
- this.#resources = parseResourcesOption(
156
- 'resources',
157
- this.#env.resources !== undefined ? envList(this.#env.resources) : resources
158
- )
112
+ // Strings: env, else the option, else the default ('' falls through); booleans keep a false.
113
+ const str = (key, fallback) => this.#envValue(key) || explicit[key] || fallback
114
+ const val = (key, fallback) => this.#envValue(key) ?? explicit[key] ?? fallback
115
+ this.#opts = {
116
+ scope: str('scope', DEFAULT_SCOPE),
117
+ lock: str('lock', DEFAULT_LOCK),
118
+ lockFile: str('lockFile', undefined),
119
+ bundle: str('bundle', DEFAULT_BUNDLE),
120
+ bundleFile: str('bundleFile', undefined),
121
+ resourcesBundleFile: str('resourcesBundleFile', undefined),
122
+ debug: val('debug', false),
123
+ childProcess: val('childProcess', false),
124
+ packageJSON: val('packageJSON', false),
125
+ fs: str('fs', undefined),
126
+ brotliQuality: this.#envValue('brotliQuality') ?? explicit.brotliQuality,
127
+ resources: parseResourcesOption('resources', this.#env.resources !== undefined ? envList(this.#env.resources) : explicit.resources),
128
+ }
129
+ const flush = env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH
130
+ this.#shardSignalFlush = Boolean(flush) && envBool('EXODUS_STASIS_SHARD_SIGNAL_FLUSH', flush)
159
131
 
160
132
  this.#checkInvariants()
161
133
  }
162
134
 
163
- // Per-field validation + cross-field invariants. Constructor (options path) and
164
- // loadConfig (disk path) both call this so the rules live in one place.
135
+ // An option's env value, parsed; undefined when unset.
136
+ #envValue(key) {
137
+ const raw = this.#env[key]
138
+ const { env, parse } = OPTIONS[key]
139
+ return raw === undefined || !parse ? raw : parse(env, raw)
140
+ }
141
+
142
+ #explicitValue(key) {
143
+ const value = this.#explicit[key]
144
+ return value !== undefined && OPTIONS[key].option ? OPTIONS[key].option(value) : value
145
+ }
146
+
165
147
  #checkInvariants() {
166
- assert.ok(VALID_SCOPE.has(this.#scope), `Invalid scope: ${this.#scope}`)
167
- assert.ok(VALID_LOCK.has(this.#lock), `Invalid lock: ${this.#lock}`)
168
- assert.ok(VALID_BUNDLE.has(this.#bundle), `Invalid bundle: ${this.#bundle}`)
169
- assert.equal(typeof this.#debug, 'boolean', 'debug must be a boolean')
170
- assert.equal(typeof this.#childProcess, 'boolean', 'childProcess must be a boolean')
171
- if (this.#fs !== undefined) {
172
- assert.ok(VALID_FS.has(this.#fs), `Invalid fs: ${this.#fs}`)
173
- // --fs patches the fs readers to capture into the bundle (add/replace) or serve them
174
- // from it (load); with any other bundle mode it has nothing to record into or read from.
175
- // Mirrors the CLI's "--fs requires --bundle=(add|replace|load)" guard.
176
- if (this.#bundle !== 'add' && this.#bundle !== 'replace' && this.#bundle !== 'load') {
177
- throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${this.#bundle}')`)
148
+ const { lock, lockFile, bundle, bundleFile, resourcesBundleFile, fs, brotliQuality } = this.#opts
149
+ for (const key of ['scope', 'lock', 'bundle', 'debug', 'childProcess', 'packageJSON']) assertOption(key, this.#opts[key])
150
+ if (brotliQuality !== undefined && !isBrotliQuality(brotliQuality)) {
151
+ throw new RangeError(`brotliQuality must be an integer 0..11 (got ${JSON.stringify(brotliQuality)})`)
152
+ }
153
+ if (fs !== undefined) {
154
+ assertOption('fs', fs)
155
+ // --fs captures into the bundle (add/replace) or serves from it (load); other modes have nothing to do.
156
+ if (!['add', 'replace', 'load'].includes(bundle)) {
157
+ throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${bundle}')`)
178
158
  }
179
159
  }
180
- if (this.#bundleFile !== undefined) assert.equal(typeof this.#bundleFile, 'string', 'bundleFile must be a string')
181
- if (this.#lockFile !== undefined) {
182
- assert.equal(typeof this.#lockFile, 'string', 'lockFile must be a string')
183
- // lockFile is only meaningful when there IS a lockfile. Lock modes that opt out
184
- // (none / ignore) would silently ignore the path -- catch the misconfig explicitly.
185
- if (this.#lock === 'none' || this.#lock === 'ignore') {
186
- throw new RangeError(`lockFile requires an active lock mode (got lock='${this.#lock}')`)
160
+ if (bundleFile !== undefined) assertOption('bundleFile', bundleFile)
161
+ if (lockFile !== undefined) {
162
+ assertOption('lockFile', lockFile)
163
+ if (lock === 'none' || lock === 'ignore') {
164
+ throw new RangeError(`lockFile requires an active lock mode (got lock='${lock}')`)
187
165
  }
188
166
  }
189
- if (this.#resourcesBundleFile !== undefined) {
190
- assert.equal(typeof this.#resourcesBundleFile, 'string', 'resourcesBundleFile must be a string')
191
- // The split is only meaningful when there IS a bundle to split. With bundle=none / ignore the
192
- // option would be silently inert -- catch the misconfiguration explicitly instead.
193
- if (this.#bundle === 'none' || this.#bundle === 'ignore') {
194
- throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${this.#bundle}')`)
167
+ if (resourcesBundleFile !== undefined) {
168
+ assertOption('resourcesBundleFile', resourcesBundleFile)
169
+ if (bundle === 'none' || bundle === 'ignore') {
170
+ throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${bundle}')`)
195
171
  }
196
172
  }
197
173
 
198
- // Cross-path collision checks: the three write targets (lockFile, bundleFile,
199
- // resourcesBundleFile) must each name a distinct on-disk file. Canonicalize via
200
- // resolve() + realpathSync so './x.br' vs 'x.br', and two symlinks to the same
201
- // inode, both compare equal -- a raw string compare would let `./out/x.br` and
202
- // `out/x.br` slip past and the second writer would silently clobber the first.
174
+ // Write targets must be distinct: canonicalize so './x.br' vs 'x.br' and symlinks to one inode compare equal.
203
175
  const claimed = new Map()
204
- for (const [label, value] of [
205
- ['lockFile', this.#lockFile],
206
- ['bundleFile', this.#bundleFile],
207
- ['resourcesBundleFile', this.#resourcesBundleFile],
208
- ]) {
176
+ for (const label of ['lockFile', 'bundleFile', 'resourcesBundleFile']) {
177
+ const value = this.#opts[label]
209
178
  if (value === undefined) continue
210
- const canonical = canonicalizePath(value)
179
+ const canonical = canonicalizePath(value, this.#host)
211
180
  if (claimed.has(canonical)) {
212
181
  throw new RangeError(`${label} '${value}' targets the same file as ${claimed.get(canonical)}; each must be a distinct path`)
213
182
  }
214
183
  claimed.set(canonical, label)
215
184
  }
216
185
 
217
- // bundle=load needs a trust root for source bytes: frozen pins each file's sha512 in
218
- // the lockfile and we cross-check it on load; otherwise the bundle is itself
219
- // authoritative -- lock=none with no lockfile on disk, or lock=ignore with a lockfile
220
- // deliberately bypassed.
221
- // WARNING: the lockfile attests source bytes, entries, module identity, and
222
- // (when it records them) resolutions and loader formats. Lockfiles predating
223
- // a given attestation cover only what they recorded (bytes at minimum).
224
- if (this.#bundle === 'load' && this.#lock !== 'frozen' && this.#lock !== 'none' && this.#lock !== 'ignore') {
186
+ // bundle=load needs a trust root: frozen pins each file's sha512, else the bundle itself is it (none/ignore).
187
+ if (bundle === 'load' && !['frozen', 'none', 'ignore'].includes(lock)) {
225
188
  throw new RangeError('bundle=load is incompatible with lock=(add|replace)')
226
189
  }
227
190
 
228
- // bundle=frozen places no constraint on lock: unlike load it never *serves* the
229
- // bundle's bytes, it reads each file from disk and verifies it against the bundle's
230
- // own recorded bytes/resolutions/formats (the bundle is itself the trust root, so it
231
- // needs no sibling lockfile -- it "operates as a lockfile"). It composes with any lock
232
- // mode, and (being a real bundle) satisfies the "needs a lockfile or a bundle" rule
233
- // below -- which only rejects leaving both unset.
234
- if (this.#lock === 'none' && this.#bundle === 'none') {
191
+ // bundle=frozen deliberately constrains no lock mode: it verifies disk against the bundle, its own trust root.
192
+ if (lock === 'none' && bundle === 'none') {
235
193
  throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
236
194
  }
237
195
  }
238
196
 
239
197
  loadConfig(json) {
240
- const {
241
- scope = this.#scope,
242
- lock = this.#lock,
243
- bundle = this.#bundle,
244
- bundleFile = this.#bundleFile,
245
- resourcesBundleFile = this.#resourcesBundleFile,
246
- debug = this.#debug,
247
- childProcess = this.#childProcess,
248
- fs = this.#fs,
249
- resources,
250
- ...rest
251
- } = JSON.parse(json)
252
- assert.equal(Object.keys(rest).length, 0)
253
- this.#scope = scope
254
- this.#lock = lock
255
- this.#bundle = bundle
256
- // Coerce '' -> undefined to match the constructor: an empty-string path is "unset"
257
- // everywhere downstream (State consumes bundleFile truthily), but #checkInvariants would
258
- // otherwise resolve('') -> cwd and claim it as a write target.
259
- this.#bundleFile = bundleFile || undefined
260
- this.#resourcesBundleFile = resourcesBundleFile || undefined
261
- this.#debug = debug
262
- this.#childProcess = childProcess
263
- this.#fs = fs
264
- if (resources !== undefined) this.#resources = parseResourcesOption('stasis.config.json', resources)
198
+ const config = JSON.parse(json)
199
+ const keys = Object.keys(config)
200
+ assert.equal(keys.filter((key) => !CONFIG_FILE_KEYS.includes(key)).length, 0)
201
+ for (const key of keys) {
202
+ if (key === 'resources') this.#opts.resources = parseResourcesOption('stasis.config.json', config.resources)
203
+ // '' -> undefined like the constructor: otherwise canonicalizePath('') claims cwd as a write target.
204
+ else if (key === 'bundleFile' || key === 'resourcesBundleFile') this.#opts[key] = config[key] || undefined
205
+ else this.#opts[key] = config[key]
206
+ }
265
207
  this.#checkInvariants()
266
208
 
267
209
  try {
268
- if (this.#env.scope !== undefined) assert.equal(this.#scope, this.#env.scope)
269
- if (this.#env.lock !== undefined) assert.equal(this.#lock, this.#env.lock)
270
- if (this.#env.bundle !== undefined) assert.equal(this.#bundle, this.#env.bundle)
271
- if (this.#env.bundleFile !== undefined) assert.equal(this.#bundleFile, this.#env.bundleFile)
272
- if (this.#env.resourcesBundleFile !== undefined) assert.equal(this.#resourcesBundleFile, this.#env.resourcesBundleFile)
273
- if (this.#env.debug !== undefined) assert.equal(this.#debug, envBool(this.#env.debug))
274
- if (this.#env.childProcess !== undefined) assert.equal(this.#childProcess, envBool(this.#env.childProcess))
275
- if (this.#env.fs !== undefined) assert.equal(this.#fs, this.#env.fs)
276
- if (this.#env.resources !== undefined) {
277
- assert.ok(extSetsEqual(this.#resources, parseResourcesOption('env', envList(this.#env.resources))),
278
- 'resources in stasis.config.json must match EXODUS_STASIS_RESOURCES')
210
+ for (const key of CONFIG_FILE_KEYS) {
211
+ if (this.#env[key] !== undefined) {
212
+ assertSame(key, this.#opts[key], this.#envValue(key), 'resources in stasis.config.json must match EXODUS_STASIS_RESOURCES')
213
+ }
279
214
  }
280
- // Explicit constructor options are equally authoritative: an explicit
281
- // `--scope=full` shouldn't be silently overridden by an on-disk
282
- // `{"scope":"node_modules"}`. The asserts mirror the env block above.
283
- if (this.#explicit.scope !== undefined) assert.equal(this.#scope, this.#explicit.scope)
284
- if (this.#explicit.lock !== undefined) assert.equal(this.#lock, this.#explicit.lock)
285
- if (this.#explicit.bundle !== undefined) assert.equal(this.#bundle, this.#explicit.bundle)
286
- if (this.#explicit.bundleFile !== undefined) assert.equal(this.#bundleFile, this.#explicit.bundleFile)
287
- if (this.#explicit.resourcesBundleFile !== undefined) assert.equal(this.#resourcesBundleFile, this.#explicit.resourcesBundleFile)
288
- if (this.#explicit.debug !== undefined) assert.equal(this.#debug, this.#explicit.debug)
289
- if (this.#explicit.childProcess !== undefined) assert.equal(this.#childProcess, this.#explicit.childProcess)
290
- if (this.#explicit.fs !== undefined) assert.equal(this.#fs, this.#explicit.fs)
291
- if (this.#explicit.resources !== undefined) {
292
- assert.ok(extSetsEqual(this.#resources, parseResourcesOption('options', this.#explicit.resources)),
293
- 'resources in stasis.config.json must match the resources option')
215
+ // Explicit constructor options are equally authoritative: an on-disk config can't override --scope=full.
216
+ for (const key of CONFIG_FILE_KEYS) {
217
+ if (this.#explicit[key] !== undefined) {
218
+ assertSame(key, this.#opts[key], this.#explicitValue(key), 'resources in stasis.config.json must match the resources option')
219
+ }
294
220
  }
295
221
  } catch (cause) {
296
222
  throw new Error('Flags/env can not override stasis.config.json', { cause })
@@ -298,129 +224,124 @@ export class Config {
298
224
  }
299
225
 
300
226
  get bundleFile() {
301
- return this.#bundleFile
227
+ return this.#opts.bundleFile
302
228
  }
303
229
 
304
- // When set, State reads/writes the lockfile at this exact path instead of
305
- // discovering `stasis.lock.json` at the project root. Set via the CLI,
306
- // `EXODUS_STASIS_LOCK_FILE`, or direct State construction; bundler plugins
307
- // can't set it (they always share the ambient lockfile). Unset -> default
308
- // discovery applies.
230
+ // Exact lockfile path, bypassing `stasis.lock.json` discovery; bundler plugins can't set it.
309
231
  get lockFile() {
310
- return this.#lockFile
232
+ return this.#opts.lockFile
311
233
  }
312
234
 
313
- // When set, State.write() emits resources to this file and code-only to bundleFile;
314
- // bundle=load reads both. Unset is the default unified-bundle behavior.
235
+ // When set, resources go to this file and code-only to bundleFile; bundle=load reads both.
315
236
  get resourcesBundleFile() {
316
- return this.#resourcesBundleFile
237
+ return this.#opts.resourcesBundleFile
317
238
  }
318
239
 
319
- // The parsed `resources` allowlist: a Set of lowercase extensions or extensionless
320
- // filenames that classifyExtension treats as asset payloads. Drives both the plugins'
321
- // per-import classification and State's `--fs` capture, so the two share one list.
322
- // Empty Set when no allowlist was configured (option or EXODUS_STASIS_RESOURCES).
240
+ // Set of lowercase extensions/filenames treated as asset payloads.
323
241
  get resources() {
324
- return this.#resources
242
+ return this.#opts.resources
325
243
  }
326
244
 
327
245
  get debug() {
328
- return this.#debug
246
+ return this.#opts.debug
329
247
  }
330
248
 
331
- // Opt-in (CLI --child-process / EXODUS_STASIS_CHILD_PROCESS / "childProcess": true in
332
- // stasis.config.json): enable cross-process capture forwarding. A forked child (e.g. a
333
- // Metro transform worker) writes a shard of what it captured into a root-owned dir, and
334
- // the root merges it before writing -- so files only a child loads (a worker's babel
335
- // toolchain) are attested. Off by default: the shard dir is a process-coordination channel,
336
- // so it's only created when explicitly enabled. Not attested (not in `values`), like debug.
249
+ // Opt-in cross-process capture forwarding: a forked child writes a shard the root merges. Not attested.
337
250
  get childProcess() {
338
- return this.#childProcess
251
+ return this.#opts.childProcess
252
+ }
253
+
254
+ // Opt-in: bundle every bundled module's package.json even if the run never reached it. Not attested.
255
+ get packageJSON() {
256
+ return this.#opts.packageJSON
339
257
  }
340
258
 
341
- // The --fs hook mode: 'sync' patches the sync fs readers, 'async' additionally patches
342
- // their async (callback + fs.promises) counterparts, undefined leaves fs untouched. Set via
343
- // --fs / EXODUS_STASIS_FS / "fs" in stasis.config.json; the runtime loader (hooks.js) reads
344
- // this on State init to decide whether (and how) to install the fs hooks. Not serialized --
345
- // a how-to-run flag like debug/childProcess, not an attested property of the bundle.
259
+ // Env-only: a capturing child flushes its shard on SIGTERM (jest-worker force-kills Metro workers),
260
+ // then re-delivers the signal. Not a user option, not attested.
261
+ get shardSignalFlush() {
262
+ return this.#shardSignalFlush
263
+ }
264
+
265
+ // --fs hook mode: 'sync' patches the sync readers, 'async' both; undefined leaves fs untouched. Not serialized.
346
266
  get fs() {
347
- return this.#fs
267
+ return this.#opts.fs
268
+ }
269
+
270
+ // Brotli quality (0..11); undefined -> DEFAULT_BROTLI_QUALITY. Not serialized -- output decompresses identically.
271
+ get brotliQuality() {
272
+ return this.#opts.brotliQuality
348
273
  }
349
274
 
350
275
  get values() {
351
- return { scope: this.#scope }
276
+ return { scope: this.#opts.scope }
352
277
  }
353
278
 
354
279
  get bundle() {
355
- return this.#bundle !== 'none' && this.#bundle !== 'ignore'
280
+ return this.#opts.bundle !== 'none' && this.#opts.bundle !== 'ignore'
356
281
  }
357
282
 
358
283
  get bundleMode() {
359
- return this.#bundle
284
+ return this.#opts.bundle
360
285
  }
361
286
 
362
287
  get ignoreBundle() {
363
- return this.#bundle === 'ignore'
288
+ return this.#opts.bundle === 'ignore'
364
289
  }
365
290
 
366
291
  get writeBundle() {
367
- return this.#bundle === 'add' || this.#bundle === 'replace'
292
+ return this.#opts.bundle === 'add' || this.#opts.bundle === 'replace'
368
293
  }
369
294
 
370
295
  get replaceBundle() {
371
- return this.#bundle === 'replace'
296
+ return this.#opts.bundle === 'replace'
372
297
  }
373
298
 
374
299
  get loadBundle() {
375
- return this.#bundle === 'load'
300
+ return this.#opts.bundle === 'load'
376
301
  }
377
302
 
378
- // bundle=frozen: the bundle is a read-only attestation, like a frozen lockfile.
379
- // It is loaded (its bytes/resolutions/entries/modules become the attested set) but
380
- // never rewritten, and every file/resolution observed from disk is checked against
381
- // it. Distinct from load (which serves bytes from the bundle instead of reading disk)
382
- // and from add (which loads-then-rewrites and tolerates new files).
303
+ // bundle=frozen: loaded, never rewritten, and disk is checked against it (load serves bytes instead).
383
304
  get frozenBundle() {
384
- return this.#bundle === 'frozen'
305
+ return this.#opts.bundle === 'frozen'
385
306
  }
386
307
 
387
308
  get full() {
388
- return this.#scope === 'full'
309
+ return this.#opts.scope === 'full'
389
310
  }
390
311
 
391
312
  get frozen() {
392
- return this.#lock === 'frozen'
313
+ return this.#opts.lock === 'frozen'
393
314
  }
394
315
 
395
316
  get useLockfile() {
396
- return this.#lock !== 'none' && this.#lock !== 'ignore'
317
+ return this.#opts.lock !== 'none' && this.#opts.lock !== 'ignore'
397
318
  }
398
319
 
399
320
  get ignoreLockfile() {
400
- return this.#lock === 'ignore'
321
+ return this.#opts.lock === 'ignore'
401
322
  }
402
323
 
403
324
  get writeLockfile() {
404
- return this.#lock === 'add' || this.#lock === 'replace'
325
+ return this.#opts.lock === 'add' || this.#opts.lock === 'replace'
405
326
  }
406
327
 
407
328
  get replaceLockfile() {
408
- return this.#lock === 'replace'
329
+ return this.#opts.lock === 'replace'
409
330
  }
410
331
 
411
332
  get scope() {
412
- return this.#scope
333
+ return this.#opts.scope
413
334
  }
414
335
 
415
336
  get lock() {
416
- return this.#lock
337
+ return this.#opts.lock
417
338
  }
418
339
 
419
340
  get json() {
420
- const data = { scope: this.#scope, lock: this.#lock, bundle: this.#bundle }
421
- // resources persists like scope/lock/bundle (a project-level declaration), but only
422
- // when non-empty so configs without an allowlist serialize byte-identically as before.
423
- if (this.#resources.size > 0) data.resources = [...this.#resources].toSorted()
341
+ const { scope, lock, bundle, resources } = this.#opts
342
+ const data = { scope, lock, bundle }
343
+ // Only serialize `resources` when non-empty, so configs without an allowlist stay byte-identical.
344
+ if (resources.size > 0) data.resources = [...resources].toSorted()
424
345
  return JSON.stringify(data, undefined, 2) + '\n'
425
346
  }
426
347
  }