@exodus/stasis-core 1.0.0-beta.15 → 1.0.0-beta.17

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,12 +1,11 @@
1
1
  import assert from 'node:assert/strict'
2
2
 
3
3
  import { diskHost } from './host.js'
4
+ import { POLICY_KEYS, parsePolicy } from './policy.js'
4
5
  import { canonicalizePath } from './state-util.js'
5
- import { extSetsEqual, isBrotliQuality, parseBrotliQuality, parseExtraOption, parseGeneratePrisma, parseInstallDevDependencies, parseLazyDependencies, parseResourcesOption } from './util.js'
6
+ import { BUNDLE_MODES, CONFIG_FILE, extSetsEqual, isBrotliQuality, LOCK_MODES, parseBrotliQuality, parseExtraOption, parseLockfilesOption, parseResourcesOption, SCOPES } from './util.js'
6
7
 
7
8
  export const DEFAULT_LOCK = 'add'
8
- export const DEFAULT_BUNDLE = 'none'
9
- export const DEFAULT_SCOPE = 'full'
10
9
 
11
10
  // Strict, not truthy: a truthiness parse would read 'no'/'off' as *enabling* the toggle.
12
11
  const envBool = (name, value) => {
@@ -15,20 +14,14 @@ const envBool = (name, value) => {
15
14
  throw new RangeError(`${name} must be ''/'0'/'false' or '1'/'true' (got '${value}')`)
16
15
  }
17
16
 
18
- // EXODUS_STASIS_RESOURCES is a comma-separated extension list; empty/unset means "no allowlist".
19
17
  const envList = (value) => value.split(',').map((s) => s.trim()).filter(Boolean)
20
18
 
21
- // Every option: its env var, how the env string parses (strings pass through) and, for a non-string
22
- // option, how a `new Config()` option does. `lockFile` and `bundle` are flag/env-only (never from
23
- // stasis.config.json), and the file's `lock` can only be CONFIG_FILE_LOCK; `extra` is the reverse,
24
- // stasis.config.json only (no env var or option), `entries` is `stasis bundle`'s and
25
- // `installDevDependencies`, `lazyDependencies` and `generatePrisma` the trees laid out from the
26
- // lockfile's (`stasis github-bundle`), which a run takes nothing from.
19
+ // `lockFile` and `bundle` are flag/env-only; `extra`, `entries`, TREE_FLAGS and `lockfiles` are file-only.
27
20
  const OPTIONS = {
28
- scope: { env: 'EXODUS_STASIS_SCOPE', valid: new Set(['node_modules', 'full']) },
29
- lock: { env: 'EXODUS_STASIS_LOCK', valid: new Set(['none', 'ignore', 'add', 'replace', 'frozen']) },
21
+ scope: { env: 'EXODUS_STASIS_SCOPE', valid: SCOPES },
22
+ lock: { env: 'EXODUS_STASIS_LOCK', valid: LOCK_MODES },
30
23
  lockFile: { env: 'EXODUS_STASIS_LOCK_FILE', type: 'string' },
31
- bundle: { env: 'EXODUS_STASIS_BUNDLE', valid: new Set(['none', 'ignore', 'add', 'replace', 'load', 'frozen']) },
24
+ bundle: { env: 'EXODUS_STASIS_BUNDLE', valid: BUNDLE_MODES },
32
25
  bundleFile: { env: 'EXODUS_STASIS_BUNDLE_FILE', type: 'string' },
33
26
  resourcesBundleFile: { env: 'EXODUS_STASIS_RESOURCES_BUNDLE_FILE', type: 'string' },
34
27
  debug: { env: 'EXODUS_STASIS_DEBUG', parse: envBool, type: 'boolean' },
@@ -40,73 +33,47 @@ const OPTIONS = {
40
33
  resources: { env: 'EXODUS_STASIS_RESOURCES', parse: (name, value) => parseResourcesOption('env', envList(value)), option: (value) => parseResourcesOption('options', value) },
41
34
  }
42
35
  const OPTION_KEYS = Object.keys(OPTIONS)
43
- // The trees laid out from the lockfile's flags (`stasis github-bundle`), by how each is parsed.
44
- const TREE_FLAGS = { __proto__: null, installDevDependencies: parseInstallDevDependencies, lazyDependencies: parseLazyDependencies, generatePrisma: parseGeneratePrisma }
45
- const CONFIG_FILE_KEYS = [...OPTION_KEYS.filter((key) => key !== 'lockFile' && key !== 'bundle'), 'extra', 'entries', ...Object.keys(TREE_FLAGS)]
46
- // The one mode a stasis.config.json can pin: a run that writes, loads or ignores is given its modes
47
- // explicitly (flags, env, options), never by a file.
36
+ const TREE_FLAGS = ['installDevDependencies', 'lazyDependencies', 'generatePrisma']
37
+ const CONFIG_FILE_KEYS = [...OPTION_KEYS.filter((key) => key !== 'lockFile' && key !== 'bundle'), 'extra', 'entries', ...TREE_FLAGS, 'lockfiles', ...POLICY_KEYS]
38
+ // The one mode a stasis.config.json can pin: a run that writes, loads or ignores is given its modes explicitly.
48
39
  const CONFIG_FILE_LOCK = 'frozen'
49
- const PLUGIN_OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'childProcess', 'packageJSON', 'resources']
50
40
 
51
- const assertKnownKeys = (keys, known, what) => {
41
+ export const assertKnownKeys = (keys, known, what) => {
52
42
  const unknown = keys.filter((key) => !known.includes(key))
53
43
  assert.equal(unknown.length, 0, `Unknown ${what} options: ${unknown.join(', ')}`)
54
44
  }
55
45
 
56
- // One option's membership/type rule; the cross-option rules live in #checkInvariants.
57
- function assertOption(key, value) {
46
+ // Plugins validate their options with it too, without constructing a Config (which has side effects).
47
+ export function assertOption(key, value) {
58
48
  const { valid, type } = OPTIONS[key]
59
49
  if (valid) assert.ok(valid.has(value), `Invalid ${key}: ${value}`)
60
50
  else if (type) assert.equal(typeof value, type, `${key} must be a ${type}`)
61
51
  }
62
52
 
63
- // Equal for the option's type: `resources` is a Set.
64
53
  const assertSame = (key, actual, expected, message) => {
65
54
  if (key === 'resources') assert.ok(extSetsEqual(actual, expected), message)
66
55
  else assert.equal(actual, expected)
67
56
  }
68
57
 
69
- // Plugins validate the same options without constructing a Config (which has side effects).
70
- export function validatePluginOptions(label, options) {
71
- assertKnownKeys(Object.keys(options), PLUGIN_OPTION_KEYS, label)
72
- for (const key of PLUGIN_OPTION_KEYS) {
73
- if (options[key] === undefined) continue
74
- if (key === 'resources') parseResourcesOption(label, options.resources)
75
- else assertOption(key, options[key])
76
- }
77
- }
78
-
79
- // The active Config is authoritative; options a plugin was given must agree with it.
80
- export function assertOptionsMatchConfig(config, options) {
81
- try {
82
- // `resources` is deliberately NOT checked here: it's a Set, coordinated in resolvePluginState.
83
- for (const key of PLUGIN_OPTION_KEYS) {
84
- if (key !== 'resources' && options[key] !== undefined) assert.equal(config[key === 'bundle' ? 'bundleMode' : key], options[key])
85
- }
86
- } catch (cause) {
87
- throw new Error(`Plugin options conflict with active stasis state: ${cause.message}`, { cause })
88
- }
89
- }
90
-
91
58
  export class Config {
92
59
  #env
93
60
  #host
94
61
  #explicit
62
+ #ownLock
95
63
  #opts
96
64
  #shardSignalFlush
97
65
 
98
- // Env and options must agree when both are set; #explicit is kept so a later loadConfig can't override them.
66
+ // `ownLock`: a build's, which takes no lock mode or lock file of EXODUS_STASIS_LOCK(_FILE) or stasis.config.json.
99
67
  constructor(options = {}) {
100
- const { env = process.env, host = diskHost, ...rest } = options
68
+ const { env = process.env, host = diskHost, ownLock = false, ...rest } = options
101
69
  assertKnownKeys(Object.keys(rest), OPTION_KEYS, 'Config')
102
- // An empty-string path/mode option is unset, as its resolution below treats it; #explicit must
103
- // agree, or loadConfig would refuse a stasis.config.json for not matching a phantom override.
70
+ // An empty-string path/mode option is unset; #explicit must agree, or loadConfig would refuse a phantom override.
104
71
  const explicit = Object.fromEntries(Object.entries(rest).map(([key, value]) =>
105
72
  [key, value === '' && (OPTIONS[key].valid || OPTIONS[key].type === 'string') ? undefined : value]))
106
73
  this.#host = host
107
74
  this.#explicit = explicit
108
- // An env var set to '' counts as unset.
109
- this.#env = Object.fromEntries(OPTION_KEYS.map((key) => [key, env[OPTIONS[key].env] || undefined]))
75
+ this.#env = Object.fromEntries(OPTION_KEYS.map((key) => [key, (ownLock && (key === 'lock' || key === 'lockFile')) ? undefined : env[OPTIONS[key].env] || undefined]))
76
+ this.#ownLock = ownLock
110
77
 
111
78
  try {
112
79
  for (const key of OPTION_KEYS) {
@@ -118,23 +85,24 @@ export class Config {
118
85
  throw new Error('Config options can not override stasis env', { cause })
119
86
  }
120
87
 
121
- // Strings: env, else the option, else the default ('' falls through); booleans keep a false.
88
+ // Strings: '' falls through; booleans keep a false.
122
89
  const str = (key, fallback) => this.#envValue(key) || explicit[key] || fallback
123
90
  const val = (key, fallback) => this.#envValue(key) ?? explicit[key] ?? fallback
124
91
  this.#opts = {
125
- scope: str('scope', DEFAULT_SCOPE),
92
+ scope: str('scope', 'full'),
126
93
  lock: str('lock', DEFAULT_LOCK),
127
- lockFile: str('lockFile', undefined),
128
- bundle: str('bundle', DEFAULT_BUNDLE),
129
- bundleFile: str('bundleFile', undefined),
130
- resourcesBundleFile: str('resourcesBundleFile', undefined),
94
+ lockFile: str('lockFile'),
95
+ bundle: str('bundle', 'none'),
96
+ bundleFile: str('bundleFile'),
97
+ resourcesBundleFile: str('resourcesBundleFile'),
131
98
  debug: val('debug', false),
132
99
  childProcess: val('childProcess', false),
133
100
  packageJSON: val('packageJSON', false),
134
- fs: str('fs', undefined),
101
+ fs: str('fs'),
135
102
  brotliQuality: this.#envValue('brotliQuality') ?? explicit.brotliQuality,
136
103
  resources: parseResourcesOption('resources', this.#env.resources !== undefined ? envList(this.#env.resources) : explicit.resources),
137
104
  extra: [],
105
+ policy: null,
138
106
  }
139
107
  const flush = env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH
140
108
  this.#shardSignalFlush = Boolean(flush) && envBool('EXODUS_STASIS_SHARD_SIGNAL_FLUSH', flush)
@@ -142,7 +110,6 @@ export class Config {
142
110
  this.#checkInvariants()
143
111
  }
144
112
 
145
- // An option's env value, parsed; undefined when unset.
146
113
  #envValue(key) {
147
114
  const raw = this.#env[key]
148
115
  const { env, parse } = OPTIONS[key]
@@ -155,30 +122,20 @@ export class Config {
155
122
  }
156
123
 
157
124
  #checkInvariants() {
158
- const { lock, lockFile, bundle, bundleFile, resourcesBundleFile, fs, brotliQuality } = this.#opts
159
- for (const key of ['scope', 'lock', 'bundle', 'debug', 'childProcess', 'packageJSON']) assertOption(key, this.#opts[key])
125
+ const { lock, lockFile, bundle, resourcesBundleFile, fs, brotliQuality } = this.#opts
126
+ for (const key of OPTION_KEYS) if (this.#opts[key] !== undefined) assertOption(key, this.#opts[key])
160
127
  if (brotliQuality !== undefined && !isBrotliQuality(brotliQuality)) {
161
128
  throw new RangeError(`brotliQuality must be an integer 0..11 (got ${JSON.stringify(brotliQuality)})`)
162
129
  }
163
- if (fs !== undefined) {
164
- assertOption('fs', fs)
165
- // --fs captures into the bundle (add/replace) or serves from it (load); other modes have nothing to do.
166
- if (!['add', 'replace', 'load'].includes(bundle)) {
167
- throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${bundle}')`)
168
- }
130
+ // --fs captures into the bundle (add/replace) or serves from it (load); other modes have nothing to do.
131
+ if (fs !== undefined && !['add', 'replace', 'load'].includes(bundle)) {
132
+ throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${bundle}')`)
169
133
  }
170
- if (bundleFile !== undefined) assertOption('bundleFile', bundleFile)
171
- if (lockFile !== undefined) {
172
- assertOption('lockFile', lockFile)
173
- if (lock === 'none' || lock === 'ignore') {
174
- throw new RangeError(`lockFile requires an active lock mode (got lock='${lock}')`)
175
- }
134
+ if (lockFile !== undefined && (lock === 'none' || lock === 'ignore')) {
135
+ throw new RangeError(`lockFile requires an active lock mode (got lock='${lock}')`)
176
136
  }
177
- if (resourcesBundleFile !== undefined) {
178
- assertOption('resourcesBundleFile', resourcesBundleFile)
179
- if (bundle === 'none' || bundle === 'ignore') {
180
- throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${bundle}')`)
181
- }
137
+ if (resourcesBundleFile !== undefined && (bundle === 'none' || bundle === 'ignore')) {
138
+ throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${bundle}')`)
182
139
  }
183
140
 
184
141
  // Write targets must be distinct: canonicalize so './x.br' vs 'x.br' and symlinks to one inode compare equal.
@@ -199,9 +156,7 @@ export class Config {
199
156
  }
200
157
 
201
158
  // bundle=frozen deliberately constrains no lock mode: it verifies disk against the bundle, its own trust root.
202
- if (lock === 'none' && bundle === 'none') {
203
- throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
204
- }
159
+ if (lock === 'none' && bundle === 'none') throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
205
160
  }
206
161
 
207
162
  loadConfig(json) {
@@ -211,33 +166,31 @@ export class Config {
211
166
  throw new Error('stasis.config.json: bundle can not be set here; give the bundle mode explicitly (--bundle, EXODUS_STASIS_BUNDLE)')
212
167
  }
213
168
  if (keys.includes('lock') && config.lock !== CONFIG_FILE_LOCK) {
214
- throw new Error(`stasis.config.json: lock can only be '${CONFIG_FILE_LOCK}' (got ${JSON.stringify(config.lock)}); give any other lock mode explicitly (--lock, EXODUS_STASIS_LOCK)`)
169
+ throw new Error(`${CONFIG_FILE}: lock can only be '${CONFIG_FILE_LOCK}' (got ${JSON.stringify(config.lock)}); give any other lock mode explicitly (--lock, EXODUS_STASIS_LOCK)`)
215
170
  }
216
171
  assert.equal(keys.filter((key) => !CONFIG_FILE_KEYS.includes(key)).length, 0)
217
172
  for (const key of keys) {
218
- // `stasis bundle`'s, validated there.
219
- if (key === 'entries') continue
173
+ // `stasis bundle`'s, validated there; the policy's, below.
174
+ if (key === 'entries' || POLICY_KEYS.includes(key)) continue
220
175
  // A run takes node_modules as installed, but a value github-bundle would refuse is refused here too.
221
- if (Object.hasOwn(TREE_FLAGS, key)) {
222
- TREE_FLAGS[key]('stasis.config.json', config[key])
223
- continue
224
- }
225
- if (key === 'resources') this.#opts.resources = parseResourcesOption('stasis.config.json', config.resources)
226
- else if (key === 'extra') this.#opts.extra = parseExtraOption('stasis.config.json', config.extra)
176
+ if (TREE_FLAGS.includes(key)) {
177
+ if (typeof config[key] !== 'boolean') throw new TypeError(`stasis.config.json: ${key} must be true or false, got ${JSON.stringify(config[key])}`)
178
+ } else if (key === 'lockfiles') parseLockfilesOption(CONFIG_FILE, config.lockfiles)
179
+ else if (key === 'resources') this.#opts.resources = parseResourcesOption(CONFIG_FILE, config.resources)
180
+ else if (key === 'extra') this.#opts.extra = parseExtraOption(CONFIG_FILE, config.extra)
227
181
  // '' -> undefined like the constructor: otherwise canonicalizePath('') claims cwd as a write target.
228
182
  else if (key === 'bundleFile' || key === 'resourcesBundleFile') this.#opts[key] = config[key] || undefined
229
- else this.#opts[key] = config[key]
183
+ else if (key !== 'lock' || !this.#ownLock) this.#opts[key] = config[key]
230
184
  }
185
+ this.#opts.policy = parsePolicy(CONFIG_FILE, config)
231
186
  this.#checkInvariants()
232
187
 
188
+ // Explicit constructor options are as authoritative as the env: an on-disk config can't override --scope=full.
233
189
  try {
234
190
  for (const key of CONFIG_FILE_KEYS) {
235
191
  if (this.#env[key] !== undefined) {
236
192
  assertSame(key, this.#opts[key], this.#envValue(key), 'resources in stasis.config.json must match EXODUS_STASIS_RESOURCES')
237
193
  }
238
- }
239
- // Explicit constructor options are equally authoritative: an on-disk config can't override --scope=full.
240
- for (const key of CONFIG_FILE_KEYS) {
241
194
  if (this.#explicit[key] !== undefined) {
242
195
  assertSame(key, this.#opts[key], this.#explicitValue(key), 'resources in stasis.config.json must match the resources option')
243
196
  }
@@ -261,21 +214,25 @@ export class Config {
261
214
  return this.#opts.resourcesBundleFile
262
215
  }
263
216
 
264
- // Set of lowercase extensions/filenames treated as asset payloads.
265
217
  get resources() {
266
218
  return this.#opts.resources
267
219
  }
268
220
 
269
- // stasis.config.json's `extra` patterns, attested beside what a writing run reaches (State#includeExtra). Not serialized.
221
+ // Attested beside what a writing run reaches (State#includeExtra). Not serialized.
270
222
  get extra() {
271
223
  return this.#opts.extra
272
224
  }
273
225
 
226
+ // File-only, not serialized.
227
+ get policy() {
228
+ return this.#opts.policy
229
+ }
230
+
274
231
  get debug() {
275
232
  return this.#opts.debug
276
233
  }
277
234
 
278
- // Opt-in cross-process capture forwarding: a forked child writes a shard the root merges. Not attested.
235
+ // A forked child writes a shard the root merges. Not attested.
279
236
  get childProcess() {
280
237
  return this.#opts.childProcess
281
238
  }
@@ -285,18 +242,17 @@ export class Config {
285
242
  return this.#opts.packageJSON
286
243
  }
287
244
 
288
- // Env-only: a capturing child flushes its shard on SIGTERM (jest-worker force-kills Metro workers),
289
- // then re-delivers the signal. Not a user option, not attested.
245
+ // Env-only: a capturing child flushes its shard on SIGTERM (jest-worker force-kills Metro workers). Not attested.
290
246
  get shardSignalFlush() {
291
247
  return this.#shardSignalFlush
292
248
  }
293
249
 
294
- // --fs hook mode: 'sync' patches the sync readers, 'async' both; undefined leaves fs untouched. Not serialized.
250
+ // Undefined leaves fs untouched. Not serialized.
295
251
  get fs() {
296
252
  return this.#opts.fs
297
253
  }
298
254
 
299
- // Brotli quality (0..11); undefined -> DEFAULT_BROTLI_QUALITY. Not serialized -- output decompresses identically.
255
+ // undefined -> DEFAULT_BROTLI_QUALITY. Not serialized: output decompresses identically.
300
256
  get brotliQuality() {
301
257
  return this.#opts.brotliQuality
302
258
  }
@@ -371,7 +327,7 @@ export class Config {
371
327
  const { scope, lock, resources } = this.#opts
372
328
  const data = { scope }
373
329
  if (lock === CONFIG_FILE_LOCK) data.lock = lock
374
- // Only serialize `resources` when non-empty, so configs without an allowlist stay byte-identical.
330
+ // Only when non-empty, so configs without an allowlist stay byte-identical.
375
331
  if (resources.size > 0) data.resources = [...resources].toSorted()
376
332
  return JSON.stringify(data, undefined, 2) + '\n'
377
333
  }
package/src/extract.js CHANGED
@@ -5,25 +5,18 @@ import { parseBundleBytes } from './brotli.js'
5
5
  import { Bundle } from './bundle.js'
6
6
  import { Lockfile } from './lockfile.js'
7
7
  import { sha512integrity } from './state-util.js'
8
- import { EXECUTE_BITS, canObserveExecuteBits, moduleFileKey, moduleFileKeys, relativeEscapes } from './util.js'
9
-
10
- const FILE_LOCK = 'stasis.lock.json'
11
- const LOCK_MODES = new Set(['frozen', 'add', 'replace', 'ignore', 'none'])
8
+ import { EXECUTE_BITS, canObserveExecuteBits, LOCK_FILE, LOCK_MODES, moduleFileKey, relativeEscapes } from './util.js'
12
9
 
13
10
  // Buffer.from silently drops invalid chars, so a tampered `resource:base64` could hash-spoof; require a fixed point.
14
11
  function assertCanonicalBase64(content, file) {
15
12
  const buf = Buffer.from(content, 'base64')
16
- if (buf.toString('base64') !== content) {
17
- throw new Error(`extract: non-canonical base64 in resource:base64 content for ${file}`)
18
- }
13
+ if (buf.toString('base64') !== content) throw new Error(`extract: non-canonical base64 in resource:base64 content for ${file}`)
19
14
  return buf
20
15
  }
21
16
 
22
- // Hashes the raw on-disk bytes, so decodes 'resource:base64' back first.
23
17
  export const lockfileFromBundle = (bundle) => Lockfile.fromBundle(bundle, (file, content) =>
24
18
  sha512integrity(bundle.formats.get(file) === 'resource:base64' ? assertCanonicalBase64(content, file) : content))
25
19
 
26
- // Where two parsed JSON values first differ, as a path into them, or null when they are equal.
27
20
  function firstDifference(bundle, lock, path = '') {
28
21
  if (bundle === lock) return null
29
22
  const nested = (x) => typeof x === 'object' && x !== null
@@ -47,42 +40,29 @@ function readLockfile(lockAbs) {
47
40
  }
48
41
  }
49
42
 
50
- // lock=frozen: the lockfile derived from the bundle must be the one in the output dir, every field of it --
51
- // entries, packages, hashes, imports, formats and execute bits. Compared re-serialized, so formatting is free.
52
- function assertLockfileMatches(lockAbs, derived) {
53
- const diff = firstDifference(JSON.parse(derived.serialize()), JSON.parse(readLockfile(lockAbs).serialize()))
54
- if (diff !== null) throw new Error(`extract: --lock=frozen: the bundle does not match ${lockAbs}: ${diff}`)
55
- }
56
-
57
- // lock=add: the derived lockfile is merged into the one in the output dir, which must agree with it on all
58
- // both record -- Lockfile.merge refuses any other conflict -- so what is new is recorded and nothing recorded changes,
59
- // save a payload-free stat:* record, which content of the same kind upgrades as a run's lock=add does.
43
+ // Nothing recorded changes, execute bits too, but a payload-free stat:* record, which content of its kind upgrades.
60
44
  function addToLockfile(lockAbs, derived) {
61
45
  const lock = readLockfile(lockAbs)
62
- let merged
63
46
  try {
64
- merged = lock.merge(derived)
47
+ return lock.mergeAgreeing(derived)
65
48
  } catch (cause) {
66
49
  throw new Error(`extract: --lock=add: the bundle conflicts with ${lockAbs}: ${cause.message}`, { cause })
67
50
  }
68
- // merge lets the incoming side's execute bits win, which here would change a recorded one.
69
- const recorded = moduleFileKeys(lock.modules, { scope: lock.config.scope })
70
- for (const file of moduleFileKeys(derived.modules, { scope: derived.config.scope })) {
71
- if (recorded.has(file) && lock.executable.has(file) !== derived.executable.has(file)) {
72
- throw new Error(`extract: --lock=add: the bundle conflicts with ${lockAbs}: ${file}'s execute bit differs`)
73
- }
74
- }
75
- return merged
76
51
  }
77
52
 
78
- // A file's device and inode (as bigints: a number can round a large Windows file id), undefined when there's none.
53
+ // As bigints: a number can round a large Windows file id.
79
54
  function fileId(path) {
80
55
  const stats = statSync(path, { throwIfNoEntry: false, bigint: true })
81
56
  return stats && `${stats.dev}:${stats.ino}`
82
57
  }
83
58
 
84
- // Whether the bytes for `file` are already at `abs`, so it is left as it is; throws for anything else there. Extract
85
- // never overwrites a file with other bytes, nor the bundle it reads, under its own name or another (a symlink, a hard link).
59
+ function dirsBelow(outDir, abs) {
60
+ const dirs = []
61
+ for (let d = dirname(abs); d.length > outDir.length; d = dirname(d)) dirs.push(d)
62
+ return dirs
63
+ }
64
+
65
+ // Extract never overwrites a file with other bytes, nor the bundle it reads, under any name (symlink, hard link).
86
66
  function alreadyInPlace(abs, file, content, bundleId) {
87
67
  const stats = statSync(abs, { throwIfNoEntry: false, bigint: true })
88
68
  if (stats === undefined) {
@@ -117,7 +97,7 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, lock:
117
97
 
118
98
  const outDir = resolve(cwd, output ?? '.')
119
99
  const outPrefix = outDir === sep ? outDir : `${outDir}${sep}`
120
- const lockAbs = join(outDir, FILE_LOCK)
100
+ const lockAbs = join(outDir, LOCK_FILE)
121
101
  // A file (or a dangling symlink) there holds neither a lockfile nor room for the bundle's paths.
122
102
  const outStats = statSync(outDir, { throwIfNoEntry: false })
123
103
  if (outStats === undefined ? lstatSync(outDir, { throwIfNoEntry: false }) !== undefined : !outStats.isDirectory()) {
@@ -125,76 +105,62 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, lock:
125
105
  }
126
106
  // lstat, not existsSync: a dangling symlink there is a lockfile too, so the default fails closed on it.
127
107
  const lockPresent = lstatSync(lockAbs, { throwIfNoEntry: false }) !== undefined
128
- // Unset: assert the lockfile already in the output dir, else write none.
129
108
  const lock = lockMode ?? (lockPresent ? 'frozen' : 'none')
130
109
  const frozen = lock === 'frozen'
131
110
  if (frozen && !lockPresent) throw new Error(`extract: --lock=frozen needs ${lockAbs}`)
132
111
  if (lock === 'none' && lockPresent) {
133
112
  throw new Error(`extract: unexpected ${lockAbs} with --lock=none (frozen checks the bundle against it, add merges the bundle into it, replace replaces it, ignore leaves it alone)`)
134
113
  }
135
- // ignore neither reads nor writes the lockfile; a v0 bundle derives none, so it has nothing to check against one, add or replace one with.
136
114
  if (lockPresent && !withLockfile && lock !== 'ignore') {
137
115
  throw new Error(`extract: a legacy v0 bundle can not ${{ frozen: 'be checked against', add: 'be added to', replace: 'replace' }[lock]} ${lockAbs}`)
138
116
  }
139
117
  const merging = lock === 'add' && lockPresent
140
118
 
141
- // Plan-first: every target is validated inside outDir before any write; walk modules, not the last-wins
142
- // `sources` getter. Containment is lexical -- symlinks are followed, so untrusted bundles need a fresh dir (doc/extract.md).
119
+ // Plan-first; walk modules, not the last-wins `sources` getter. Containment is lexical -- symlinks are
120
+ // followed, so untrusted bundles need a fresh dir (doc/extract.md).
143
121
  const writes = []
144
122
  const targets = new Set()
145
- let executables = 0
146
123
  for (const [dir, { files }] of bundle.modules) {
147
124
  for (const [rel, content] of Object.entries(files)) {
148
- // A `directory` capture is a listing at the dir's own path, not a file to write (its children recreate the dir).
125
+ // A listing at the dir's own path, not a file to write (its children recreate the dir).
149
126
  const key = moduleFileKey(dir, rel)
150
127
  if (bundle.formats.get(key) === 'directory') continue
151
- // The WRITE path keeps the plain join, so a non-`directory` rel === '' fails the canonical-path
152
- // check instead of writing at the bucket root.
128
+ // The plain join, so a non-`directory` rel === '' fails the canonical-path check, not writes at the bucket root.
153
129
  const file = dir === '.' ? rel : `${dir}/${rel}`
154
130
  if (typeof content !== 'string') throw new Error(`extract: bundle file content is not a string: ${file}`)
155
131
  const abs = resolve(outDir, file)
156
132
  const relToOut = relative(outDir, abs)
157
- // relativeEscapes is `../`-aware, NOT a bare startsWith('..') -- that would reject a legit `..foo` filename.
158
- if (relativeEscapes(relToOut) || !abs.startsWith(outPrefix)) {
159
- throw new Error(`extract: bundle path escapes output dir: ${file}`)
160
- }
133
+ if (relativeEscapes(relToOut) || !abs.startsWith(outPrefix)) throw new Error(`extract: bundle path escapes output dir: ${file}`)
161
134
  // A non-canonical path changes under the resolve+relative round-trip; writing it desyncs tree from lockfile.
162
135
  if (relToOut !== file) throw new Error(`extract: non-canonical bundle path: ${file}`)
163
136
  // No bundle Bundle.parse takes carries a stasis.lock.json, so no write lands on the lockfile.
164
137
  if (targets.has(abs)) throw new Error(`extract: duplicate bundle path: ${file}`)
165
138
  targets.add(abs)
166
- // Executability rides the plan tuple, so the chmod can only ever reach a file we actually wrote.
139
+ // Executability rides the plan, so the chmod can only ever reach a file we actually wrote.
167
140
  const exec = bundle.executable.has(key)
168
- if (exec) executables += 1
169
- writes.push([abs, bundle.formats.get(key) === 'resource:base64' ? assertCanonicalBase64(content, file) : content, exec, file])
141
+ writes.push({ abs, content: bundle.formats.get(key) === 'resource:base64' ? assertCanonicalBase64(content, file) : content, exec, file })
170
142
  }
171
143
  }
172
- // A planned file must not also be a parent directory of another, else the writes throw halfway through.
173
- for (const [abs] of writes) {
174
- for (let d = dirname(abs); d.length > outDir.length; d = dirname(d)) {
175
- if (targets.has(d)) {
176
- throw new Error(`extract: bundle path used as both file and directory: ${relative(outDir, d)}`)
177
- }
178
- }
144
+ // A file planned as another's parent directory would make the writes throw halfway through.
145
+ for (const { abs } of writes) {
146
+ const clash = dirsBelow(outDir, abs).find((d) => targets.has(d))
147
+ if (clash !== undefined) throw new Error(`extract: bundle path used as both file and directory: ${relative(outDir, clash)}`)
179
148
  }
180
- // Only add and replace write a lockfile, and frozen checks one; each before the first write.
181
149
  const writesLock = lock === 'add' || lock === 'replace'
182
150
  const derived = withLockfile && (frozen || writesLock) ? lockfileFromBundle(bundle) : null
183
- if (frozen) assertLockfileMatches(lockAbs, derived)
151
+ // Every field of the lockfile must match, compared re-serialized, so formatting is free.
152
+ const diff = frozen ? firstDifference(JSON.parse(derived.serialize()), JSON.parse(readLockfile(lockAbs).serialize())) : null
153
+ if (diff !== null) throw new Error(`extract: --lock=frozen: the bundle does not match ${lockAbs}: ${diff}`)
184
154
  const lockText = derived === null || frozen ? null : (merging ? addToLockfile(lockAbs, derived) : derived).serialize()
185
155
 
186
- // What is already on disk, checked whole before the first write too: each directory a write needs must be one (or
187
- // missing), and each target missing or already holding its bytes. The lockfile, which --lock governs, is no
188
- // exception to the bundle being off limits.
156
+ // What is already on disk is checked whole before the first write too; nor may the lockfile's land on the bundle.
189
157
  const bundleId = fileId(bundleAbs)
190
- if (lockText !== null && fileId(lockAbs) === bundleId) throw new Error(`extract: ${FILE_LOCK} is the bundle being extracted`)
158
+ if (lockText !== null && fileId(lockAbs) === bundleId) throw new Error(`extract: ${LOCK_FILE} is the bundle being extracted`)
191
159
  const checkedDirs = new Set()
192
160
  const inPlace = new Set()
193
- for (const [abs, content, , file] of writes) {
194
- // Top-down, so a stat never runs into a file higher up (ENOTDIR); the first missing one ends the walk.
195
- const dirs = []
196
- for (let d = dirname(abs); d.length > outDir.length; d = dirname(d)) dirs.push(d)
197
- for (const d of dirs.toReversed()) {
161
+ for (const { abs, content, file } of writes) {
162
+ // Top-down, so a stat never runs into a file higher up (ENOTDIR).
163
+ for (const d of dirsBelow(outDir, abs).toReversed()) {
198
164
  if (checkedDirs.has(d)) continue
199
165
  const stats = statSync(d, { throwIfNoEntry: false })
200
166
  if (stats === undefined && lstatSync(d, { throwIfNoEntry: false }) === undefined) break
@@ -204,8 +170,8 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, lock:
204
170
  if (alreadyInPlace(abs, file, content, bundleId)) inPlace.add(abs)
205
171
  }
206
172
 
207
- // Only the execute bit is attested, so only it is touched -- rw bits stay as written (never widen a 0600 target)
208
- // and setuid/setgid/sticky are cleared. Applied to every extracted file, one already in place too; skipped for v0, which attests no modes.
173
+ // Only the execute bit is attested, so only it is touched -- rw bits stay as written (never widen a 0600
174
+ // target) and setuid/setgid/sticky are cleared. v0 attests no modes.
209
175
  const withModes = withLockfile && canObserveExecuteBits()
210
176
  let chmodFailures = 0
211
177
  const applyMode = (abs, exec) => {
@@ -231,11 +197,10 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, lock:
231
197
  }
232
198
  }
233
199
 
234
- for (const [abs, content, exec] of writes) {
200
+ for (const { abs, content, exec } of writes) {
235
201
  if (!inPlace.has(abs)) {
236
202
  mkdirSync(dirname(abs), { recursive: true })
237
- // Exclusive: a file that appeared since the check, or a second path a case-insensitive disk folds onto an
238
- // earlier one, fails the write rather than being overwritten.
203
+ // Exclusive: a file that appeared since the check, or one a case-insensitive disk folds onto another, fails.
239
204
  writeFileSync(abs, content, { flag: 'wx' })
240
205
  }
241
206
  if (withModes) applyMode(abs, exec)
@@ -243,16 +208,17 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, lock:
243
208
  mkdirSync(outDir, { recursive: true }) // for an empty bundle, where no write created it
244
209
  if (lockText !== null) writeFileSync(lockAbs, lockText)
245
210
 
211
+ const executables = writes.filter(({ exec }) => exec).length
246
212
  const notes = [executables > 0 && `${executables} executable`, inPlace.size > 0 && `${inPlace.size} already in place`].filter(Boolean)
247
213
  const execNote = notes.length > 0 ? ` (${notes.join(', ')})` : ''
248
- const andLock = lockText !== null && !merging ? ` and ${FILE_LOCK}` : ''
249
- const lockNote = frozen ? `, verified against ${FILE_LOCK}` : merging ? `, added to ${FILE_LOCK}` : ''
214
+ const andLock = lockText !== null && !merging ? ` and ${LOCK_FILE}` : ''
215
+ const lockNote = frozen ? `, verified against ${LOCK_FILE}` : merging ? `, added to ${LOCK_FILE}` : ''
250
216
  console.warn(`[${logLabel}] Extracted ${writes.length} file(s)${execNote}${andLock} to ${outDir}${lockNote}`)
251
217
  if (chmodFailures > 0) {
252
218
  console.warn(`[${logLabel}] Warning: could not set file modes on ${chmodFailures} file(s) (the filesystem may not support them); contents were written`)
253
219
  }
254
220
  if (!withLockfile && writesLock) {
255
- console.warn(`[${logLabel}] Warning: legacy v0 bundle records no package name/version, so ${FILE_LOCK} can not be restored and was not written`)
221
+ console.warn(`[${logLabel}] Warning: legacy v0 bundle records no package name/version, so ${LOCK_FILE} can not be restored and was not written`)
256
222
  }
257
223
  return { dir: outDir, files: writes.length, executable: executables, inPlace: inPlace.size, lock }
258
224
  }