@exodus/stasis-core 1.0.0-beta.2 → 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
@@ -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 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,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
- // Options match the CLI flags (scope/lock/lockFile/bundle/bundleFile/resourcesBundleFile/debug/
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 the raw strings: ['png','svg'] and 'svg,png' are the
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
- // Env-only (no option, no stasis.config.json key): shard-channel plumbing a parent
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
- // env wins over the option; no `||` chaining -- 0 is a valid quality and falsy.
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
- // A write-side knob; like bundleFile, inert-but-harmless under read-only modes
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 patches the fs readers to capture into the bundle (add/replace) or serve them
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
- // Cross-path collision checks: the three write targets (lockFile, bundleFile,
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 for source bytes: frozen pins each file's sha512 in
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 places no constraint on lock: unlike load it never *serves* the
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
- // Coerce '' -> undefined to match the constructor: an empty-string path is "unset"
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 explicit
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
- // When set, State reads/writes the lockfile at this exact path instead of
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, State.write() emits resources to this file and code-only to bundleFile;
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
- // The parsed `resources` allowlist: a Set of lowercase extensions or extensionless
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 (CLI --child-process / EXODUS_STASIS_CHILD_PROCESS / "childProcess": true 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 (EXODUS_STASIS_SHARD_SIGNAL_FLUSH, env-only): a capturing CHILD flushes its
376
- // shard when ended by SIGTERM, then re-delivers the signal (hooks.js). Set on
377
- // process.env by StasisMetro's capture wiring, so every capturing child the build forks
378
- // after config time inherits it -- Metro's transform workers are the intended audience:
379
- // jest-worker force-kills a worker whose event loop doesn't drain within 500ms of its
380
- // END message, which would otherwise silently drop the worker's shard.
381
- // Deliberately NOT a global default (a signal listener changes a child's default-kill
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
- // The --fs hook mode: 'sync' patches the sync fs readers, 'async' additionally patches
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 (integer 0..11) for bundle writes; undefined -> brotli's default (11,
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: the bundle is a read-only attestation, like a frozen lockfile.
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 persists like scope/lock/bundle (a project-level declaration), but only
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
+ }