@exodus/stasis-core 1.0.0-beta.1 → 1.0.0-beta.3

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,44 +1,35 @@
1
1
  import assert from 'node:assert/strict'
2
2
 
3
3
  import { canonicalizePath } from './state-util.js'
4
- import { extSetsEqual, parseResourcesOption } from './util.js'
4
+ import { extSetsEqual, isBrotliQuality, parseBrotliQuality, parseResourcesOption } from './util.js'
5
5
 
6
6
  const VALID_SCOPE = new Set(['node_modules', 'full'])
7
7
  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 boolean env parsing: ''/'0'/'false' -> false, '1'/'true' -> true. Anything else
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; split + trim + drop
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 accept the same options as Config but want to validate without constructing one,
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
- // parseResourcesOption is the validator: it throws on a non-array, non-string entries,
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
- // When a plugin runs against a State that already exists (preload path), the active Config
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 intentionally NOT cross-checked here: it's a Set (needs set-equality,
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,20 +71,16 @@ export class Config {
86
71
  #resources
87
72
  #debug
88
73
  #childProcess
74
+ #packageJSON
75
+ #shardSignalFlush
89
76
  #fs
77
+ #brotliQuality
90
78
 
91
- // Options match the CLI flags (scope/lock/lockFile/bundle/bundleFile/resourcesBundleFile/debug/
92
- // resources/childProcess/fs).
93
- // Env vars take effect at construction time; if both env and an option are set they must
94
- // agree. Likewise, any explicit constructor option is treated as authoritative: a later
95
- // `loadConfig` call (which reads stasis.config.json) must agree with it -- the alternative
96
- // (silently overwriting `--scope=full` with the file's `"scope":"node_modules"`)
97
- // was a footgun the CLI couldn't detect, since the flag was happily accepted
98
- // 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.
99
80
  constructor(options = {}) {
100
- const { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, fs, ...rest } = options
81
+ const { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, packageJSON, fs, brotliQuality, ...rest } = options
101
82
  assert.equal(Object.keys(rest).length, 0, `Unknown Config options: ${Object.keys(rest).join(', ')}`)
102
- this.#explicit = { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, fs }
83
+ this.#explicit = { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, packageJSON, fs, brotliQuality }
103
84
 
104
85
  this.#env = {
105
86
  scope: process.env.EXODUS_STASIS_SCOPE || undefined,
@@ -111,7 +92,10 @@ export class Config {
111
92
  debug: process.env.EXODUS_STASIS_DEBUG || undefined,
112
93
  resources: process.env.EXODUS_STASIS_RESOURCES || undefined,
113
94
  childProcess: process.env.EXODUS_STASIS_CHILD_PROCESS || undefined,
95
+ packageJSON: process.env.EXODUS_STASIS_PACKAGE_JSON || undefined,
96
+ shardSignalFlush: process.env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH || undefined,
114
97
  fs: process.env.EXODUS_STASIS_FS || undefined,
98
+ brotliQuality: process.env.EXODUS_STASIS_BROTLI_QUALITY || undefined,
115
99
  }
116
100
 
117
101
  try {
@@ -133,10 +117,14 @@ export class Config {
133
117
  if (this.#env.childProcess !== undefined && childProcess !== undefined) {
134
118
  assert.equal(envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess), childProcess)
135
119
  }
120
+ if (this.#env.packageJSON !== undefined && packageJSON !== undefined) {
121
+ assert.equal(envBool('EXODUS_STASIS_PACKAGE_JSON', this.#env.packageJSON), packageJSON)
122
+ }
136
123
  if (this.#env.fs !== undefined && fs !== undefined) assert.equal(this.#env.fs, fs)
137
- // Compare parsed sets, not the raw strings: ['png','svg'] and 'svg,png' are the
138
- // same allowlist. An empty/unset env var is "no env opinion" (handled by `||
139
- // undefined` above), so this only fires on two genuinely different non-empty lists.
124
+ if (this.#env.brotliQuality !== undefined && brotliQuality !== undefined) {
125
+ assert.equal(parseBrotliQuality('EXODUS_STASIS_BROTLI_QUALITY', this.#env.brotliQuality), brotliQuality)
126
+ }
127
+ // Compare parsed sets, not raw strings: ['png','svg'] and 'svg,png' are the same allowlist.
140
128
  if (this.#env.resources !== undefined && resources !== undefined) {
141
129
  assert.ok(
142
130
  extSetsEqual(parseResourcesOption('env', envList(this.#env.resources)), parseResourcesOption('options', resources)),
@@ -155,10 +143,15 @@ export class Config {
155
143
  this.#resourcesBundleFile = this.#env.resourcesBundleFile || resourcesBundleFile || undefined
156
144
  this.#debug = this.#env.debug !== undefined ? envBool('EXODUS_STASIS_DEBUG', this.#env.debug) : (debug ?? false)
157
145
  this.#childProcess = this.#env.childProcess !== undefined ? envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess) : (childProcess ?? false)
158
- // env wins over the option, like scope/lock/bundle; undefined means "fs untouched" (off).
146
+ this.#packageJSON = this.#env.packageJSON !== undefined ? envBool('EXODUS_STASIS_PACKAGE_JSON', this.#env.packageJSON) : (packageJSON ?? false)
147
+ this.#shardSignalFlush = this.#env.shardSignalFlush !== undefined
148
+ ? envBool('EXODUS_STASIS_SHARD_SIGNAL_FLUSH', this.#env.shardSignalFlush)
149
+ : false
159
150
  this.#fs = this.#env.fs || fs || undefined
160
- // env wins over the option (it's the process-wide signal); parseResourcesOption
161
- // normalizes both to a Set of lowercase extensions/filenames, or empty when neither set.
151
+ // No `||` chaining here -- 0 is a valid quality and falsy.
152
+ this.#brotliQuality = this.#env.brotliQuality !== undefined
153
+ ? parseBrotliQuality('EXODUS_STASIS_BROTLI_QUALITY', this.#env.brotliQuality)
154
+ : brotliQuality
162
155
  this.#resources = parseResourcesOption(
163
156
  'resources',
164
157
  this.#env.resources !== undefined ? envList(this.#env.resources) : resources
@@ -167,19 +160,19 @@ export class Config {
167
160
  this.#checkInvariants()
168
161
  }
169
162
 
170
- // Per-field validation + cross-field invariants. Constructor (options path) and
171
- // loadConfig (disk path) both call this so the rules live in one place.
172
163
  #checkInvariants() {
173
164
  assert.ok(VALID_SCOPE.has(this.#scope), `Invalid scope: ${this.#scope}`)
174
165
  assert.ok(VALID_LOCK.has(this.#lock), `Invalid lock: ${this.#lock}`)
175
166
  assert.ok(VALID_BUNDLE.has(this.#bundle), `Invalid bundle: ${this.#bundle}`)
176
167
  assert.equal(typeof this.#debug, 'boolean', 'debug must be a boolean')
177
168
  assert.equal(typeof this.#childProcess, 'boolean', 'childProcess must be a boolean')
169
+ assert.equal(typeof this.#packageJSON, 'boolean', 'packageJSON must be a boolean')
170
+ if (this.#brotliQuality !== undefined && !isBrotliQuality(this.#brotliQuality)) {
171
+ throw new RangeError(`brotliQuality must be an integer 0..11 (got ${JSON.stringify(this.#brotliQuality)})`)
172
+ }
178
173
  if (this.#fs !== undefined) {
179
174
  assert.ok(VALID_FS.has(this.#fs), `Invalid fs: ${this.#fs}`)
180
- // --fs patches the fs readers to capture into the bundle (add/replace) or serve them
181
- // from it (load); with any other bundle mode it has nothing to record into or read from.
182
- // 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.
183
176
  if (this.#bundle !== 'add' && this.#bundle !== 'replace' && this.#bundle !== 'load') {
184
177
  throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${this.#bundle}')`)
185
178
  }
@@ -187,26 +180,18 @@ export class Config {
187
180
  if (this.#bundleFile !== undefined) assert.equal(typeof this.#bundleFile, 'string', 'bundleFile must be a string')
188
181
  if (this.#lockFile !== undefined) {
189
182
  assert.equal(typeof this.#lockFile, 'string', 'lockFile must be a string')
190
- // lockFile is only meaningful when there IS a lockfile. Lock modes that opt out
191
- // (none / ignore) would silently ignore the path -- catch the misconfig explicitly.
192
183
  if (this.#lock === 'none' || this.#lock === 'ignore') {
193
184
  throw new RangeError(`lockFile requires an active lock mode (got lock='${this.#lock}')`)
194
185
  }
195
186
  }
196
187
  if (this.#resourcesBundleFile !== undefined) {
197
188
  assert.equal(typeof this.#resourcesBundleFile, 'string', 'resourcesBundleFile must be a string')
198
- // The split is only meaningful when there IS a bundle to split. With bundle=none / ignore the
199
- // option would be silently inert -- catch the misconfiguration explicitly instead.
200
189
  if (this.#bundle === 'none' || this.#bundle === 'ignore') {
201
190
  throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${this.#bundle}')`)
202
191
  }
203
192
  }
204
193
 
205
- // Cross-path collision checks: the three write targets (lockFile, bundleFile,
206
- // resourcesBundleFile) must each name a distinct on-disk file. Canonicalize via
207
- // resolve() + realpathSync so './x.br' vs 'x.br', and two symlinks to the same
208
- // inode, both compare equal -- a raw string compare would let `./out/x.br` and
209
- // `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.
210
195
  const claimed = new Map()
211
196
  for (const [label, value] of [
212
197
  ['lockFile', this.#lockFile],
@@ -221,23 +206,12 @@ export class Config {
221
206
  claimed.set(canonical, label)
222
207
  }
223
208
 
224
- // bundle=load needs a trust root for source bytes: frozen pins each file's sha512 in
225
- // the lockfile and we cross-check it on load; otherwise the bundle is itself
226
- // authoritative -- lock=none with no lockfile on disk, or lock=ignore with a lockfile
227
- // deliberately bypassed.
228
- // WARNING: the lockfile attests source bytes, entries, module identity, and
229
- // (when it records them) resolutions and loader formats. Lockfiles predating
230
- // 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).
231
210
  if (this.#bundle === 'load' && this.#lock !== 'frozen' && this.#lock !== 'none' && this.#lock !== 'ignore') {
232
211
  throw new RangeError('bundle=load is incompatible with lock=(add|replace)')
233
212
  }
234
213
 
235
- // bundle=frozen places no constraint on lock: unlike load it never *serves* the
236
- // bundle's bytes, it reads each file from disk and verifies it against the bundle's
237
- // own recorded bytes/resolutions/formats (the bundle is itself the trust root, so it
238
- // needs no sibling lockfile -- it "operates as a lockfile"). It composes with any lock
239
- // mode, and (being a real bundle) satisfies the "needs a lockfile or a bundle" rule
240
- // 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.
241
215
  if (this.#lock === 'none' && this.#bundle === 'none') {
242
216
  throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
243
217
  }
@@ -252,7 +226,9 @@ export class Config {
252
226
  resourcesBundleFile = this.#resourcesBundleFile,
253
227
  debug = this.#debug,
254
228
  childProcess = this.#childProcess,
229
+ packageJSON = this.#packageJSON,
255
230
  fs = this.#fs,
231
+ brotliQuality = this.#brotliQuality,
256
232
  resources,
257
233
  ...rest
258
234
  } = JSON.parse(json)
@@ -260,14 +236,14 @@ export class Config {
260
236
  this.#scope = scope
261
237
  this.#lock = lock
262
238
  this.#bundle = bundle
263
- // Coerce '' -> undefined to match the constructor: an empty-string path is "unset"
264
- // everywhere downstream (State consumes bundleFile truthily), but #checkInvariants would
265
- // otherwise resolve('') -> cwd and claim it as a write target.
239
+ // '' -> undefined like the constructor: otherwise canonicalizePath('') claims cwd as a write target.
266
240
  this.#bundleFile = bundleFile || undefined
267
241
  this.#resourcesBundleFile = resourcesBundleFile || undefined
268
242
  this.#debug = debug
269
243
  this.#childProcess = childProcess
244
+ this.#packageJSON = packageJSON
270
245
  this.#fs = fs
246
+ this.#brotliQuality = brotliQuality
271
247
  if (resources !== undefined) this.#resources = parseResourcesOption('stasis.config.json', resources)
272
248
  this.#checkInvariants()
273
249
 
@@ -279,14 +255,16 @@ export class Config {
279
255
  if (this.#env.resourcesBundleFile !== undefined) assert.equal(this.#resourcesBundleFile, this.#env.resourcesBundleFile)
280
256
  if (this.#env.debug !== undefined) assert.equal(this.#debug, envBool('EXODUS_STASIS_DEBUG', this.#env.debug))
281
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))
282
259
  if (this.#env.fs !== undefined) assert.equal(this.#fs, this.#env.fs)
260
+ if (this.#env.brotliQuality !== undefined) {
261
+ assert.equal(this.#brotliQuality, parseBrotliQuality('EXODUS_STASIS_BROTLI_QUALITY', this.#env.brotliQuality))
262
+ }
283
263
  if (this.#env.resources !== undefined) {
284
264
  assert.ok(extSetsEqual(this.#resources, parseResourcesOption('env', envList(this.#env.resources))),
285
265
  'resources in stasis.config.json must match EXODUS_STASIS_RESOURCES')
286
266
  }
287
- // Explicit constructor options are equally authoritative: an explicit
288
- // `--scope=full` shouldn't be silently overridden by an on-disk
289
- // `{"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.
290
268
  if (this.#explicit.scope !== undefined) assert.equal(this.#scope, this.#explicit.scope)
291
269
  if (this.#explicit.lock !== undefined) assert.equal(this.#lock, this.#explicit.lock)
292
270
  if (this.#explicit.bundle !== undefined) assert.equal(this.#bundle, this.#explicit.bundle)
@@ -294,7 +272,9 @@ export class Config {
294
272
  if (this.#explicit.resourcesBundleFile !== undefined) assert.equal(this.#resourcesBundleFile, this.#explicit.resourcesBundleFile)
295
273
  if (this.#explicit.debug !== undefined) assert.equal(this.#debug, this.#explicit.debug)
296
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)
297
276
  if (this.#explicit.fs !== undefined) assert.equal(this.#fs, this.#explicit.fs)
277
+ if (this.#explicit.brotliQuality !== undefined) assert.equal(this.#brotliQuality, this.#explicit.brotliQuality)
298
278
  if (this.#explicit.resources !== undefined) {
299
279
  assert.ok(extSetsEqual(this.#resources, parseResourcesOption('options', this.#explicit.resources)),
300
280
  'resources in stasis.config.json must match the resources option')
@@ -308,25 +288,17 @@ export class Config {
308
288
  return this.#bundleFile
309
289
  }
310
290
 
311
- // When set, State reads/writes the lockfile at this exact path instead of
312
- // discovering `stasis.lock.json` at the project root. Set via the CLI,
313
- // `EXODUS_STASIS_LOCK_FILE`, or direct State construction; bundler plugins
314
- // can't set it (they always share the ambient lockfile). Unset -> default
315
- // discovery applies.
291
+ // Exact lockfile path, bypassing `stasis.lock.json` discovery; bundler plugins can't set it.
316
292
  get lockFile() {
317
293
  return this.#lockFile
318
294
  }
319
295
 
320
- // When set, State.write() emits resources to this file and code-only to bundleFile;
321
- // 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.
322
297
  get resourcesBundleFile() {
323
298
  return this.#resourcesBundleFile
324
299
  }
325
300
 
326
- // The parsed `resources` allowlist: a Set of lowercase extensions or extensionless
327
- // filenames that classifyExtension treats as asset payloads. Drives both the plugins'
328
- // per-import classification and State's `--fs` capture, so the two share one list.
329
- // Empty Set when no allowlist was configured (option or EXODUS_STASIS_RESOURCES).
301
+ // Set of lowercase extensions/filenames treated as asset payloads.
330
302
  get resources() {
331
303
  return this.#resources
332
304
  }
@@ -335,25 +307,32 @@ export class Config {
335
307
  return this.#debug
336
308
  }
337
309
 
338
- // Opt-in (CLI --child-process / EXODUS_STASIS_CHILD_PROCESS / "childProcess": true in
339
- // stasis.config.json): enable cross-process capture forwarding. A forked child (e.g. a
340
- // Metro transform worker) writes a shard of what it captured into a root-owned dir, and
341
- // the root merges it before writing -- so files only a child loads (a worker's babel
342
- // toolchain) are attested. Off by default: the shard dir is a process-coordination channel,
343
- // 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.
344
311
  get childProcess() {
345
312
  return this.#childProcess
346
313
  }
347
314
 
348
- // The --fs hook mode: 'sync' patches the sync fs readers, 'async' additionally patches
349
- // their async (callback + fs.promises) counterparts, undefined leaves fs untouched. Set via
350
- // --fs / EXODUS_STASIS_FS / "fs" in stasis.config.json; the runtime loader (hooks.js) reads
351
- // this on State init to decide whether (and how) to install the fs hooks. Not serialized --
352
- // a how-to-run flag like debug/childProcess, not an attested property of the bundle.
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.
322
+ get shardSignalFlush() {
323
+ return this.#shardSignalFlush
324
+ }
325
+
326
+ // --fs hook mode: 'sync' patches the sync readers, 'async' both; undefined leaves fs untouched. Not serialized.
353
327
  get fs() {
354
328
  return this.#fs
355
329
  }
356
330
 
331
+ // Brotli quality (0..11); undefined -> DEFAULT_BROTLI_QUALITY. Not serialized -- output decompresses identically.
332
+ get brotliQuality() {
333
+ return this.#brotliQuality
334
+ }
335
+
357
336
  get values() {
358
337
  return { scope: this.#scope }
359
338
  }
@@ -382,11 +361,7 @@ export class Config {
382
361
  return this.#bundle === 'load'
383
362
  }
384
363
 
385
- // bundle=frozen: the bundle is a read-only attestation, like a frozen lockfile.
386
- // It is loaded (its bytes/resolutions/entries/modules become the attested set) but
387
- // never rewritten, and every file/resolution observed from disk is checked against
388
- // it. Distinct from load (which serves bytes from the bundle instead of reading disk)
389
- // 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).
390
365
  get frozenBundle() {
391
366
  return this.#bundle === 'frozen'
392
367
  }
@@ -425,8 +400,7 @@ export class Config {
425
400
 
426
401
  get json() {
427
402
  const data = { scope: this.#scope, lock: this.#lock, bundle: this.#bundle }
428
- // resources persists like scope/lock/bundle (a project-level declaration), but only
429
- // 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.
430
404
  if (this.#resources.size > 0) data.resources = [...this.#resources].toSorted()
431
405
  return JSON.stringify(data, undefined, 2) + '\n'
432
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
+ }