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

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.
@@ -6,6 +6,7 @@ import { once } from 'node:events'
6
6
  import { fileURLToPath } from 'node:url'
7
7
  import { basename, resolve } from 'node:path'
8
8
  import { existsSync, realpathSync } from 'node:fs'
9
+ import { constants as osConstants } from 'node:os'
9
10
  import assert from 'node:assert/strict'
10
11
  import pkg from '../package.json' with { type: 'json' }
11
12
 
@@ -103,8 +104,9 @@ if (command === '-v' || command === '--version') {
103
104
  setEnv('EXODUS_STASIS_RESOURCES', resources)
104
105
  const nodeArgs = ['--import', import.meta.resolve('../src/loader.js')]
105
106
  const child = spawn(process.execPath, [...nodeArgs, ...argv], { stdio: 'inherit' })
106
- const [code] = await once(child, 'close')
107
- process.exitCode = code
107
+ const [code, signal] = await once(child, 'close')
108
+ // code is null when the child died from a signal; report 128+signo (shell convention) instead of the implicit 0
109
+ process.exitCode = code ?? 128 + (osConstants.signals[signal] ?? 0)
108
110
  } else if (command === 'prune') {
109
111
  if (argv.length > 1) usage('Error: prune takes at most one path argument')
110
112
  const root = argv[0] ? resolve(argv[0]) : process.cwd()
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@exodus/stasis-core",
3
- "version": "1.0.0-beta.0",
3
+ "version": "1.0.0-beta.1",
4
4
  "description": "Zero-dependency stasis runtime",
5
5
  "type": "module",
6
6
  "exports": {
package/src/bundle.js CHANGED
@@ -125,7 +125,7 @@ export class Bundle {
125
125
  assert(typeof json.modules === 'object' && json.modules !== null)
126
126
  for (const [dir, info] of Object.entries(json.modules)) {
127
127
  assert(dir.includes('node_modules'))
128
- assert(!dir.startsWith('..'))
128
+ assert(!posixPathEscapes(dir))
129
129
  assert(info?.name && info.version && info.files)
130
130
  modules.set(dir, normalize(info))
131
131
  }
@@ -134,7 +134,7 @@ export class Bundle {
134
134
  assert(json.sources && typeof json.sources === 'object')
135
135
  for (const [dir, info] of Object.entries(json.sources)) {
136
136
  assert(!dir.includes('node_modules'))
137
- assert(!dir.startsWith('..'))
137
+ assert(!posixPathEscapes(dir))
138
138
  assert(info?.name && info.version && info.files)
139
139
  modules.set(dir, normalize(info))
140
140
  }
@@ -166,15 +166,18 @@ export class Bundle {
166
166
  assert(json.sources === undefined)
167
167
  }
168
168
  for (const [, { files }] of modules) {
169
- for (const rel of Object.keys(files)) assert(!rel.startsWith('..'))
169
+ // posixPathEscapes (not a '..' prefix check) so a mid-path escape or an
170
+ // absolute path fails too, matching Lockfile.parse. rel === '' (a
171
+ // `directory` capture keyed at a module root) normalizes to '.' and passes.
172
+ for (const rel of Object.keys(files)) assert(!posixPathEscapes(rel))
170
173
  }
171
174
  } else {
172
175
  // v0 legacy: flat sources at top level, regrouped by inferred module dir.
173
176
  assert(json.sources)
174
177
  for (const [path, content] of Object.entries(json.sources)) {
175
- assert(!path.startsWith('..'))
178
+ assert(!posixPathEscapes(path))
176
179
  const { dir, rel, name } = inferModuleDir(path)
177
- assert(!dir.startsWith('..') && !rel.startsWith('..'))
180
+ assert(!posixPathEscapes(dir) && !posixPathEscapes(rel))
178
181
  if (!modules.has(dir)) modules.set(dir, { name, version: null, files: Object.create(null) })
179
182
  modules.get(dir).files[rel] = content
180
183
  }
package/src/config.js CHANGED
@@ -16,7 +16,14 @@ export const DEFAULT_LOCK = 'add'
16
16
  export const DEFAULT_BUNDLE = 'none'
17
17
  export const DEFAULT_SCOPE = 'full'
18
18
 
19
- const envBool = (value) => Boolean(value && value !== '0')
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.
22
+ const envBool = (name, value) => {
23
+ if (value === '' || value === '0' || value === 'false') return false
24
+ if (value === '1' || value === 'true') return true
25
+ 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
22
29
  // empties so '' and ' png , svg ' normalize predictably (parseResourcesOption then
@@ -121,10 +128,10 @@ export class Config {
121
128
  assert.equal(this.#env.resourcesBundleFile, resourcesBundleFile)
122
129
  }
123
130
  if (this.#env.debug !== undefined && debug !== undefined) {
124
- assert.equal(envBool(this.#env.debug), debug)
131
+ assert.equal(envBool('EXODUS_STASIS_DEBUG', this.#env.debug), debug)
125
132
  }
126
133
  if (this.#env.childProcess !== undefined && childProcess !== undefined) {
127
- assert.equal(envBool(this.#env.childProcess), childProcess)
134
+ assert.equal(envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess), childProcess)
128
135
  }
129
136
  if (this.#env.fs !== undefined && fs !== undefined) assert.equal(this.#env.fs, fs)
130
137
  // Compare parsed sets, not the raw strings: ['png','svg'] and 'svg,png' are the
@@ -146,8 +153,8 @@ export class Config {
146
153
  this.#bundle = this.#env.bundle || bundle || DEFAULT_BUNDLE
147
154
  this.#bundleFile = this.#env.bundleFile || bundleFile || undefined
148
155
  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)
156
+ this.#debug = this.#env.debug !== undefined ? envBool('EXODUS_STASIS_DEBUG', this.#env.debug) : (debug ?? false)
157
+ this.#childProcess = this.#env.childProcess !== undefined ? envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess) : (childProcess ?? false)
151
158
  // env wins over the option, like scope/lock/bundle; undefined means "fs untouched" (off).
152
159
  this.#fs = this.#env.fs || fs || undefined
153
160
  // env wins over the option (it's the process-wide signal); parseResourcesOption
@@ -270,8 +277,8 @@ export class Config {
270
277
  if (this.#env.bundle !== undefined) assert.equal(this.#bundle, this.#env.bundle)
271
278
  if (this.#env.bundleFile !== undefined) assert.equal(this.#bundleFile, this.#env.bundleFile)
272
279
  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))
280
+ if (this.#env.debug !== undefined) assert.equal(this.#debug, envBool('EXODUS_STASIS_DEBUG', this.#env.debug))
281
+ if (this.#env.childProcess !== undefined) assert.equal(this.#childProcess, envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess))
275
282
  if (this.#env.fs !== undefined) assert.equal(this.#fs, this.#env.fs)
276
283
  if (this.#env.resources !== undefined) {
277
284
  assert.ok(extSetsEqual(this.#resources, parseResourcesOption('env', envList(this.#env.resources))),
package/src/state.js CHANGED
@@ -444,71 +444,8 @@ export class State {
444
444
  : lockProbe
445
445
  const lockPath = explicitLockPath || join(rootDir, FILE_LOCK)
446
446
 
447
- if (lock && !this.config.useLockfile && !this.config.ignoreLockfile) {
448
- throw new Error(`Unexpected ${lockPath} with config.lock = 'none'`)
449
- }
450
- if (sources && !this.config.writeBundle && !this.config.loadBundle && !this.config.ignoreBundle && !this.config.frozenBundle) {
451
- throw new Error(`Unexpected ${sourcesPath} with config.bundle = 'none'`)
452
- }
453
-
454
- // A frozen bundle is self-attesting -- it verifies disk against the bundle's
455
- // own bytes, so (unlike load/add) it needs no sibling lockfile and is exempt
456
- // from this "a lockfile is required before a bundle's sources can be trusted"
457
- // guard. This is what lets bundle=frozen compose with lock=add (bootstrapping a
458
- // fresh lockfile from the verified run) without a pre-existing lockfile.
459
- if (sources && !lock && this.config.useLockfile && !this.config.replaceLockfile && !this.config.frozenBundle) {
460
- throw new Error('stasis.lock.json missing, can not use sources')
461
- }
462
-
463
- if (lock && this.config.useLockfile && !this.config.replaceLockfile) {
464
- const lockfile = Lockfile.parse(lock)
465
- if (this.config.frozen) assert.equal(lockfile.config.scope, this.config.scope)
466
-
467
- const includeSources = lockfile.config.scope === 'full' && this.config.full
468
- for (const [dir, info] of lockfile.modules) {
469
- if (!dir.includes('node_modules') && !includeSources) continue
470
- this.modules.set(dir, info)
471
- }
472
- if (includeSources) this.entries = lockfile.entries
473
-
474
- for (const [dir, { files }] of this.modules) {
475
- for (const [name, hash] of Object.entries(files)) {
476
- noupsert(this.hashes, join(dir, name), hash)
477
- }
478
- }
479
- this.#lockImports = lockfile.imports
480
- this.#lockFormats = lockfile.formats
481
- // Frozen promises verification, but a lockfile predating resolution
482
- // or format attestation can only vouch for bytes -- those metadata
483
- // (from a bundle OR observed on disk) go unchecked until it's
484
- // regenerated.
485
- if (this.config.frozen && this.#lockImports === null) {
486
- console.warn('[stasis] Warning: lockfile does not attest resolutions; they are trusted as-is. Regenerate the lockfile to enable this check.')
487
- }
488
- if (this.config.frozen && this.#lockFormats === null) {
489
- console.warn('[stasis] Warning: lockfile does not attest formats; they are trusted as-is. Regenerate the lockfile to enable this check.')
490
- }
491
- lockfileLoaded = true
492
- this.#lockfileLoaded = true
493
- }
494
-
495
- if (sources && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
496
- this.#absorbCodeBundle(sources, sourcesPath, lockfileLoaded)
497
- }
498
-
499
- // Split-bundle layout: when `resourcesBundleFile` is configured, resources
500
- // live in a separate file. Load it as a standalone Bundle (entries empty,
501
- // imports empty, formats restricted to resource tags) and union into the
502
- // state already absorbed from `bundleFile`. The strict-shape asserts catch
503
- // a writer that accidentally leaked code into the resources file or a
504
- // tampered file claiming entries/imports it shouldn't have.
505
- if (this.config.resourcesBundleFile) {
506
- const resourcesPath = this.config.resourcesBundleFile
507
- const resourcesData = readFileSyncMaybe(dirname(resourcesPath), basename(resourcesPath))
508
- if (resourcesData && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
509
- this.#absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath })
510
- }
511
- }
447
+ lockfileLoaded = this.#absorbLockfile(lock, lockPath)
448
+ this.#loadBundleArtifacts(sources, sourcesPath, lockfileLoaded)
512
449
 
513
450
  // The innermost matching rootDir is authoritative (per-dir opt-in, see above), so stop
514
451
  // scanning once committed. An explicit/config `bundleFile` is rootDir-independent: without
@@ -522,67 +459,33 @@ export class State {
522
459
  // Explicit lockfile path with no other discovery indicator at any rootDir: the
523
460
  // discovery loop never set `loaded`, so the lockfile branch above never ran. Process
524
461
  // the explicit lockfile here against the already-resolved `this.root` (outermost
525
- // package.json) so the run still has its attestation. Inlines the same gates as the
526
- // in-loop branch -- a future refactor could merge the two by extracting a helper.
462
+ // package.json) so the run still has its attestation.
527
463
  if (!loaded && explicitLockPath) {
528
464
  const lock = readFileSyncMaybe(dirname(explicitLockPath), basename(explicitLockPath), 'utf-8')
529
- if (lock && !this.config.useLockfile && !this.config.ignoreLockfile) {
530
- throw new Error(`Unexpected ${explicitLockPath} with config.lock = 'none'`)
531
- }
532
- if (lock && this.config.useLockfile && !this.config.replaceLockfile) {
533
- const lockfile = Lockfile.parse(lock)
534
- if (this.config.frozen) assert.equal(lockfile.config.scope, this.config.scope)
535
- const includeSources = lockfile.config.scope === 'full' && this.config.full
536
- for (const [dir, info] of lockfile.modules) {
537
- if (!dir.includes('node_modules') && !includeSources) continue
538
- this.modules.set(dir, info)
539
- }
540
- if (includeSources) this.entries = lockfile.entries
541
- for (const [dir, { files }] of this.modules) {
542
- for (const [name, hash] of Object.entries(files)) {
543
- noupsert(this.hashes, join(dir, name), hash)
544
- }
545
- }
546
- this.#lockImports = lockfile.imports
547
- this.#lockFormats = lockfile.formats
548
- if (this.config.frozen && this.#lockImports === null) {
549
- console.warn('[stasis] Warning: lockfile does not attest resolutions; they are trusted as-is. Regenerate the lockfile to enable this check.')
550
- }
551
- if (this.config.frozen && this.#lockFormats === null) {
552
- console.warn('[stasis] Warning: lockfile does not attest formats; they are trusted as-is. Regenerate the lockfile to enable this check.')
553
- }
554
- lockfileLoaded = true
555
- this.#lockfileLoaded = true
556
- }
557
- }
558
-
559
- // Explicit (flag/env) bundleFile with no rootDir-dependent indicator at any rootDir: like the
560
- // explicit lockfile above, it was suppressed as a root-detection signal so it couldn't pull the
561
- // root down to the innermost package, so the loop never loaded it. Load it here against
562
- // `this.root` (the outermost package.json) -- the same root capture commits to when no signal
563
- // exists -- so its capture-root-relative keys line up with how they're looked up. Inlines the
564
- // same gates as the in-loop bundle branch.
565
- if (!loaded && explicitBundlePath) {
566
- const sourcesPath = this.config.bundleFile
567
- const sources = readFileSyncMaybe(dirname(sourcesPath), basename(sourcesPath))
568
- if (sources && !this.config.writeBundle && !this.config.loadBundle && !this.config.ignoreBundle && !this.config.frozenBundle) {
569
- throw new Error(`Unexpected ${sourcesPath} with config.bundle = 'none'`)
570
- }
571
- if (sources && !lockfileLoaded && this.config.useLockfile && !this.config.replaceLockfile && !this.config.frozenBundle) {
572
- throw new Error('stasis.lock.json missing, can not use sources')
573
- }
574
- if (sources && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
575
- this.#absorbCodeBundle(sources, sourcesPath, lockfileLoaded)
576
- }
577
- // Split-bundle resources: same post-loop treatment (resourcesBundleFile is likewise an
578
- // explicit, rootDir-independent path). Mirrors the in-loop resources branch.
579
- if (this.config.resourcesBundleFile) {
580
- const resourcesPath = this.config.resourcesBundleFile
581
- const resourcesData = readFileSyncMaybe(dirname(resourcesPath), basename(resourcesPath))
582
- if (resourcesData && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
583
- this.#absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath })
584
- }
585
- }
465
+ lockfileLoaded = this.#absorbLockfile(lock, explicitLockPath)
466
+ }
467
+
468
+ // Explicit (flag/env) bundleFile and/or resourcesBundleFile with no rootDir-dependent
469
+ // indicator at any rootDir: like the explicit lockfile above, an explicit bundleFile was
470
+ // suppressed as a root-detection signal so it couldn't pull the root down to the innermost
471
+ // package, so the loop never loaded it. Load it here against `this.root` (the outermost
472
+ // package.json) -- the same root capture commits to when no signal exists -- so its
473
+ // capture-root-relative keys line up with how they're looked up. `resourcesBundleFile` is in
474
+ // the gate for the resources-only split shape (#absorbResourcesBundle documents it as legal):
475
+ // with no code bundle on disk there is no other reason to reach the loader here, yet the
476
+ // explicit resources half must still be absorbed. Post-loop, both paths are necessarily
477
+ // flag/env: a stasis.config.json could only have set them by also committing the loop.
478
+ //
479
+ // NB: the outermost root depends on where the upward walk stopped (PROJECT_CWD, .git,
480
+ // pnpm-workspace.yaml -- see potentialRoots above). Capture and load must agree on that
481
+ // boundary for the keys to line up: e.g. a capture under yarn (PROJECT_CWD set to an inner
482
+ // workspace dir) and a bare load of the same bundle (walks up to the repo's .git) commit
483
+ // different roots and fail with "outside the project root" / "not attested".
484
+ if (!loaded && (explicitBundlePath || this.config.resourcesBundleFile)) {
485
+ const sources = explicitBundlePath
486
+ ? readFileSyncMaybe(dirname(explicitBundlePath), basename(explicitBundlePath))
487
+ : null
488
+ this.#loadBundleArtifacts(sources, explicitBundlePath, lockfileLoaded)
586
489
  }
587
490
 
588
491
  // Frozen modes must have actually loaded their attestation. Asserting here --
@@ -624,6 +527,87 @@ export class State {
624
527
  liveStates().add(this)
625
528
  }
626
529
 
530
+ // Absorb a lockfile's attestation into this State: the run-scope module/hash maps, the
531
+ // imports/formats attestation, and the frozen-mode warnings for lockfiles predating those
532
+ // attestations. Shared by the discovery loop (a committed rootDir) and the post-loop fallback
533
+ // for an explicit `config.lockFile` -- a rootDir-independent path, so it is suppressed as a
534
+ // root-detection signal and loaded at the outermost root instead. Returns whether the lockfile
535
+ // was actually absorbed (the caller's `lockfileLoaded`).
536
+ #absorbLockfile(lock, lockPath) {
537
+ if (lock && !this.config.useLockfile && !this.config.ignoreLockfile) {
538
+ throw new Error(`Unexpected ${lockPath} with config.lock = 'none'`)
539
+ }
540
+ if (!lock || !this.config.useLockfile || this.config.replaceLockfile) return false
541
+ const lockfile = Lockfile.parse(lock)
542
+ if (this.config.frozen) assert.equal(lockfile.config.scope, this.config.scope)
543
+
544
+ const includeSources = lockfile.config.scope === 'full' && this.config.full
545
+ for (const [dir, info] of lockfile.modules) {
546
+ if (!dir.includes('node_modules') && !includeSources) continue
547
+ this.modules.set(dir, info)
548
+ }
549
+ if (includeSources) this.entries = lockfile.entries
550
+
551
+ for (const [dir, { files }] of this.modules) {
552
+ for (const [name, hash] of Object.entries(files)) {
553
+ noupsert(this.hashes, join(dir, name), hash)
554
+ }
555
+ }
556
+ this.#lockImports = lockfile.imports
557
+ this.#lockFormats = lockfile.formats
558
+ // Frozen promises verification, but a lockfile predating resolution
559
+ // or format attestation can only vouch for bytes -- those metadata
560
+ // (from a bundle OR observed on disk) go unchecked until it's
561
+ // regenerated.
562
+ if (this.config.frozen && this.#lockImports === null) {
563
+ console.warn('[stasis] Warning: lockfile does not attest resolutions; they are trusted as-is. Regenerate the lockfile to enable this check.')
564
+ }
565
+ if (this.config.frozen && this.#lockFormats === null) {
566
+ console.warn('[stasis] Warning: lockfile does not attest formats; they are trusted as-is. Regenerate the lockfile to enable this check.')
567
+ }
568
+ this.#lockfileLoaded = true
569
+ return true
570
+ }
571
+
572
+ // Gate and load the bundle artifacts for an already-committed root: the unified
573
+ // code[+resource] bundle read from `sourcesPath`, plus the split `resourcesBundleFile` when
574
+ // one is configured. Shared by the discovery loop and the post-loop explicit-path fallback so
575
+ // the mode guards cannot drift between the two. `sources` may be null -- no bundle on disk, or
576
+ // a resources-only deployment -- in which case only the resources half applies.
577
+ //
578
+ // The missing-lockfile guard tests `lockfileLoaded` where the pre-extraction in-loop code
579
+ // tested raw lockfile presence; equivalent at this call point, since whenever the guard can
580
+ // fire (useLockfile && !replaceLockfile) #absorbLockfile absorbed the lockfile iff it existed.
581
+ #loadBundleArtifacts(sources, sourcesPath, lockfileLoaded) {
582
+ if (sources && !this.config.writeBundle && !this.config.loadBundle && !this.config.ignoreBundle && !this.config.frozenBundle) {
583
+ throw new Error(`Unexpected ${sourcesPath} with config.bundle = 'none'`)
584
+ }
585
+ // A frozen bundle is self-attesting -- it verifies disk against the bundle's
586
+ // own bytes, so (unlike load/add) it needs no sibling lockfile and is exempt
587
+ // from this "a lockfile is required before a bundle's sources can be trusted"
588
+ // guard. This is what lets bundle=frozen compose with lock=add (bootstrapping a
589
+ // fresh lockfile from the verified run) without a pre-existing lockfile.
590
+ if (sources && !lockfileLoaded && this.config.useLockfile && !this.config.replaceLockfile && !this.config.frozenBundle) {
591
+ throw new Error('stasis.lock.json missing, can not use sources')
592
+ }
593
+ if (sources && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
594
+ this.#absorbCodeBundle(sources, sourcesPath, lockfileLoaded)
595
+ }
596
+ // Split-bundle layout: when `resourcesBundleFile` is configured, resources
597
+ // live in a separate file. Load it as a standalone Bundle (entries empty,
598
+ // imports empty, formats restricted to resource tags) and union into the
599
+ // state already absorbed from `bundleFile`. The strict-shape asserts catch
600
+ // a writer that accidentally leaked code into the resources file or a
601
+ // tampered file claiming entries/imports it shouldn't have.
602
+ if (this.config.resourcesBundleFile) {
603
+ const resourcesPath = this.config.resourcesBundleFile
604
+ const resourcesData = readFileSyncMaybe(dirname(resourcesPath), basename(resourcesPath))
605
+ if (resourcesData && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
606
+ this.#absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath })
607
+ }
608
+ }
609
+ }
610
+
627
611
  // Absorb a unified code+resource bundle's metadata and payloads into this State. Shared by the
628
612
  // discovery loop (a committed rootDir carrying a stasis signal) and the post-loop fallback that
629
613
  // loads an explicit (rootDir-independent) bundleFile against the outermost root.