@exodus/stasis-core 1.0.0-beta.9 → 1.0.0-rc.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.
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, 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,16 +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` is flag/env-only (never from stasis.config.json).
19
+ // `lockFile` and `bundle` are flag/env-only; `extra`, `entries`, TREE_FLAGS and `lockfiles` are file-only.
23
20
  const OPTIONS = {
24
- scope: { env: 'EXODUS_STASIS_SCOPE', valid: new Set(['node_modules', 'full']) },
25
- lock: { env: 'EXODUS_STASIS_LOCK', valid: new Set(['none', 'ignore', 'add', 'replace', 'frozen']) },
21
+ scope: { env: 'EXODUS_STASIS_SCOPE', valid: SCOPES },
22
+ lock: { env: 'EXODUS_STASIS_LOCK', valid: LOCK_MODES },
26
23
  lockFile: { env: 'EXODUS_STASIS_LOCK_FILE', type: 'string' },
27
- bundle: { env: 'EXODUS_STASIS_BUNDLE', valid: new Set(['none', 'ignore', 'add', 'replace', 'load', 'frozen']) },
24
+ bundle: { env: 'EXODUS_STASIS_BUNDLE', valid: BUNDLE_MODES },
28
25
  bundleFile: { env: 'EXODUS_STASIS_BUNDLE_FILE', type: 'string' },
29
26
  resourcesBundleFile: { env: 'EXODUS_STASIS_RESOURCES_BUNDLE_FILE', type: 'string' },
30
27
  debug: { env: 'EXODUS_STASIS_DEBUG', parse: envBool, type: 'boolean' },
@@ -36,68 +33,47 @@ const OPTIONS = {
36
33
  resources: { env: 'EXODUS_STASIS_RESOURCES', parse: (name, value) => parseResourcesOption('env', envList(value)), option: (value) => parseResourcesOption('options', value) },
37
34
  }
38
35
  const OPTION_KEYS = Object.keys(OPTIONS)
39
- const CONFIG_FILE_KEYS = OPTION_KEYS.filter((key) => key !== 'lockFile')
40
- const PLUGIN_OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'childProcess', 'packageJSON', 'resources']
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.
39
+ const CONFIG_FILE_LOCK = 'frozen'
41
40
 
42
- const assertKnownKeys = (keys, known, what) => {
41
+ export const assertKnownKeys = (keys, known, what) => {
43
42
  const unknown = keys.filter((key) => !known.includes(key))
44
43
  assert.equal(unknown.length, 0, `Unknown ${what} options: ${unknown.join(', ')}`)
45
44
  }
46
45
 
47
- // One option's membership/type rule; the cross-option rules live in #checkInvariants.
48
- 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) {
49
48
  const { valid, type } = OPTIONS[key]
50
49
  if (valid) assert.ok(valid.has(value), `Invalid ${key}: ${value}`)
51
50
  else if (type) assert.equal(typeof value, type, `${key} must be a ${type}`)
52
51
  }
53
52
 
54
- // Equal for the option's type: `resources` is a Set.
55
53
  const assertSame = (key, actual, expected, message) => {
56
54
  if (key === 'resources') assert.ok(extSetsEqual(actual, expected), message)
57
55
  else assert.equal(actual, expected)
58
56
  }
59
57
 
60
- // Plugins validate the same options without constructing a Config (which has side effects).
61
- export function validatePluginOptions(label, options) {
62
- assertKnownKeys(Object.keys(options), PLUGIN_OPTION_KEYS, label)
63
- for (const key of PLUGIN_OPTION_KEYS) {
64
- if (options[key] === undefined) continue
65
- if (key === 'resources') parseResourcesOption(label, options.resources)
66
- else assertOption(key, options[key])
67
- }
68
- }
69
-
70
- // The active Config is authoritative; options a plugin was given must agree with it.
71
- export function assertOptionsMatchConfig(config, options) {
72
- try {
73
- // `resources` is deliberately NOT checked here: it's a Set, coordinated in resolvePluginState.
74
- for (const key of PLUGIN_OPTION_KEYS) {
75
- if (key !== 'resources' && options[key] !== undefined) assert.equal(config[key === 'bundle' ? 'bundleMode' : key], options[key])
76
- }
77
- } catch (cause) {
78
- throw new Error(`Plugin options conflict with active stasis state: ${cause.message}`, { cause })
79
- }
80
- }
81
-
82
58
  export class Config {
83
59
  #env
84
60
  #host
85
61
  #explicit
62
+ #ownLock
86
63
  #opts
87
64
  #shardSignalFlush
88
65
 
89
- // 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.
90
67
  constructor(options = {}) {
91
- const { env = process.env, host = diskHost, ...rest } = options
68
+ const { env = process.env, host = diskHost, ownLock = false, ...rest } = options
92
69
  assertKnownKeys(Object.keys(rest), OPTION_KEYS, 'Config')
93
- // An empty-string path/mode option is unset, as its resolution below treats it; #explicit must
94
- // agree, or loadConfig would refuse a stasis.config.json for not matching a phantom override.
70
+ // An empty-string path/mode option is unset; #explicit must agree, or loadConfig would refuse a phantom override.
95
71
  const explicit = Object.fromEntries(Object.entries(rest).map(([key, value]) =>
96
72
  [key, value === '' && (OPTIONS[key].valid || OPTIONS[key].type === 'string') ? undefined : value]))
97
73
  this.#host = host
98
74
  this.#explicit = explicit
99
- // An env var set to '' counts as unset.
100
- this.#env = Object.fromEntries(OPTION_KEYS.map((key) => [key, env[OPTIONS[key].env] || undefined]))
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
101
77
 
102
78
  try {
103
79
  for (const key of OPTION_KEYS) {
@@ -109,22 +85,24 @@ export class Config {
109
85
  throw new Error('Config options can not override stasis env', { cause })
110
86
  }
111
87
 
112
- // Strings: env, else the option, else the default ('' falls through); booleans keep a false.
88
+ // Strings: '' falls through; booleans keep a false.
113
89
  const str = (key, fallback) => this.#envValue(key) || explicit[key] || fallback
114
90
  const val = (key, fallback) => this.#envValue(key) ?? explicit[key] ?? fallback
115
91
  this.#opts = {
116
- scope: str('scope', DEFAULT_SCOPE),
92
+ scope: str('scope', 'full'),
117
93
  lock: str('lock', DEFAULT_LOCK),
118
- lockFile: str('lockFile', undefined),
119
- bundle: str('bundle', DEFAULT_BUNDLE),
120
- bundleFile: str('bundleFile', undefined),
121
- resourcesBundleFile: str('resourcesBundleFile', undefined),
94
+ lockFile: str('lockFile'),
95
+ bundle: str('bundle', 'none'),
96
+ bundleFile: str('bundleFile'),
97
+ resourcesBundleFile: str('resourcesBundleFile'),
122
98
  debug: val('debug', false),
123
99
  childProcess: val('childProcess', false),
124
100
  packageJSON: val('packageJSON', false),
125
- fs: str('fs', undefined),
101
+ fs: str('fs'),
126
102
  brotliQuality: this.#envValue('brotliQuality') ?? explicit.brotliQuality,
127
103
  resources: parseResourcesOption('resources', this.#env.resources !== undefined ? envList(this.#env.resources) : explicit.resources),
104
+ extra: [],
105
+ policy: null,
128
106
  }
129
107
  const flush = env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH
130
108
  this.#shardSignalFlush = Boolean(flush) && envBool('EXODUS_STASIS_SHARD_SIGNAL_FLUSH', flush)
@@ -132,7 +110,6 @@ export class Config {
132
110
  this.#checkInvariants()
133
111
  }
134
112
 
135
- // An option's env value, parsed; undefined when unset.
136
113
  #envValue(key) {
137
114
  const raw = this.#env[key]
138
115
  const { env, parse } = OPTIONS[key]
@@ -145,30 +122,20 @@ export class Config {
145
122
  }
146
123
 
147
124
  #checkInvariants() {
148
- const { lock, lockFile, bundle, bundleFile, resourcesBundleFile, fs, brotliQuality } = this.#opts
149
- for (const key of ['scope', 'lock', 'bundle', 'debug', 'childProcess', 'packageJSON']) assertOption(key, this.#opts[key])
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])
150
127
  if (brotliQuality !== undefined && !isBrotliQuality(brotliQuality)) {
151
128
  throw new RangeError(`brotliQuality must be an integer 0..11 (got ${JSON.stringify(brotliQuality)})`)
152
129
  }
153
- if (fs !== undefined) {
154
- assertOption('fs', fs)
155
- // --fs captures into the bundle (add/replace) or serves from it (load); other modes have nothing to do.
156
- if (!['add', 'replace', 'load'].includes(bundle)) {
157
- throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${bundle}')`)
158
- }
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}')`)
159
133
  }
160
- if (bundleFile !== undefined) assertOption('bundleFile', bundleFile)
161
- if (lockFile !== undefined) {
162
- assertOption('lockFile', lockFile)
163
- if (lock === 'none' || lock === 'ignore') {
164
- throw new RangeError(`lockFile requires an active lock mode (got lock='${lock}')`)
165
- }
134
+ if (lockFile !== undefined && (lock === 'none' || lock === 'ignore')) {
135
+ throw new RangeError(`lockFile requires an active lock mode (got lock='${lock}')`)
166
136
  }
167
- if (resourcesBundleFile !== undefined) {
168
- assertOption('resourcesBundleFile', resourcesBundleFile)
169
- if (bundle === 'none' || bundle === 'ignore') {
170
- throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${bundle}')`)
171
- }
137
+ if (resourcesBundleFile !== undefined && (bundle === 'none' || bundle === 'ignore')) {
138
+ throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${bundle}')`)
172
139
  }
173
140
 
174
141
  // Write targets must be distinct: canonicalize so './x.br' vs 'x.br' and symlinks to one inode compare equal.
@@ -189,31 +156,41 @@ export class Config {
189
156
  }
190
157
 
191
158
  // bundle=frozen deliberately constrains no lock mode: it verifies disk against the bundle, its own trust root.
192
- if (lock === 'none' && bundle === 'none') {
193
- throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
194
- }
159
+ if (lock === 'none' && bundle === 'none') throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
195
160
  }
196
161
 
197
162
  loadConfig(json) {
198
163
  const config = JSON.parse(json)
199
164
  const keys = Object.keys(config)
165
+ if (keys.includes('bundle')) {
166
+ throw new Error('stasis.config.json: bundle can not be set here; give the bundle mode explicitly (--bundle, EXODUS_STASIS_BUNDLE)')
167
+ }
168
+ if (keys.includes('lock') && config.lock !== CONFIG_FILE_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)`)
170
+ }
200
171
  assert.equal(keys.filter((key) => !CONFIG_FILE_KEYS.includes(key)).length, 0)
201
172
  for (const key of keys) {
202
- if (key === 'resources') this.#opts.resources = parseResourcesOption('stasis.config.json', config.resources)
173
+ // `stasis bundle`'s, validated there; the policy's, below.
174
+ if (key === 'entries' || POLICY_KEYS.includes(key)) continue
175
+ // A run takes node_modules as installed, but a value github-bundle would refuse is refused here too.
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)
203
181
  // '' -> undefined like the constructor: otherwise canonicalizePath('') claims cwd as a write target.
204
182
  else if (key === 'bundleFile' || key === 'resourcesBundleFile') this.#opts[key] = config[key] || undefined
205
- else this.#opts[key] = config[key]
183
+ else if (key !== 'lock' || !this.#ownLock) this.#opts[key] = config[key]
206
184
  }
185
+ this.#opts.policy = parsePolicy(CONFIG_FILE, config)
207
186
  this.#checkInvariants()
208
187
 
188
+ // Explicit constructor options are as authoritative as the env: an on-disk config can't override --scope=full.
209
189
  try {
210
190
  for (const key of CONFIG_FILE_KEYS) {
211
191
  if (this.#env[key] !== undefined) {
212
192
  assertSame(key, this.#opts[key], this.#envValue(key), 'resources in stasis.config.json must match EXODUS_STASIS_RESOURCES')
213
193
  }
214
- }
215
- // Explicit constructor options are equally authoritative: an on-disk config can't override --scope=full.
216
- for (const key of CONFIG_FILE_KEYS) {
217
194
  if (this.#explicit[key] !== undefined) {
218
195
  assertSame(key, this.#opts[key], this.#explicitValue(key), 'resources in stasis.config.json must match the resources option')
219
196
  }
@@ -237,16 +214,25 @@ export class Config {
237
214
  return this.#opts.resourcesBundleFile
238
215
  }
239
216
 
240
- // Set of lowercase extensions/filenames treated as asset payloads.
241
217
  get resources() {
242
218
  return this.#opts.resources
243
219
  }
244
220
 
221
+ // Attested beside what a writing run reaches (State#includeExtra). Not serialized.
222
+ get extra() {
223
+ return this.#opts.extra
224
+ }
225
+
226
+ // File-only, not serialized.
227
+ get policy() {
228
+ return this.#opts.policy
229
+ }
230
+
245
231
  get debug() {
246
232
  return this.#opts.debug
247
233
  }
248
234
 
249
- // 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.
250
236
  get childProcess() {
251
237
  return this.#opts.childProcess
252
238
  }
@@ -256,18 +242,17 @@ export class Config {
256
242
  return this.#opts.packageJSON
257
243
  }
258
244
 
259
- // Env-only: a capturing child flushes its shard on SIGTERM (jest-worker force-kills Metro workers),
260
- // then re-delivers the signal. Not a user option, not attested.
245
+ // Env-only: a capturing child flushes its shard on SIGTERM (jest-worker force-kills Metro workers). Not attested.
261
246
  get shardSignalFlush() {
262
247
  return this.#shardSignalFlush
263
248
  }
264
249
 
265
- // --fs hook mode: 'sync' patches the sync readers, 'async' both; undefined leaves fs untouched. Not serialized.
250
+ // Undefined leaves fs untouched. Not serialized.
266
251
  get fs() {
267
252
  return this.#opts.fs
268
253
  }
269
254
 
270
- // Brotli quality (0..11); undefined -> DEFAULT_BROTLI_QUALITY. Not serialized -- output decompresses identically.
255
+ // undefined -> DEFAULT_BROTLI_QUALITY. Not serialized: output decompresses identically.
271
256
  get brotliQuality() {
272
257
  return this.#opts.brotliQuality
273
258
  }
@@ -337,10 +322,12 @@ export class Config {
337
322
  return this.#opts.lock
338
323
  }
339
324
 
325
+ // As a stasis.config.json holds it: `lock` only where it is the one a file can pin, `bundle` never.
340
326
  get json() {
341
- const { scope, lock, bundle, resources } = this.#opts
342
- const data = { scope, lock, bundle }
343
- // Only serialize `resources` when non-empty, so configs without an allowlist stay byte-identical.
327
+ const { scope, lock, resources } = this.#opts
328
+ const data = { scope }
329
+ if (lock === CONFIG_FILE_LOCK) data.lock = lock
330
+ // Only when non-empty, so configs without an allowlist stay byte-identical.
344
331
  if (resources.size > 0) data.resources = [...resources].toSorted()
345
332
  return JSON.stringify(data, undefined, 2) + '\n'
346
333
  }
package/src/extract.js CHANGED
@@ -1,54 +1,92 @@
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'
1
+ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
2
+ import { dirname, join, relative, resolve, sep } from 'node:path'
4
3
 
4
+ 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, moduleInfo } from './util.js'
9
-
10
- const FILE_LOCK = 'stasis.lock.json'
8
+ import { EXECUTE_BITS, canObserveExecuteBits, LOCK_FILE, LOCK_MODES, moduleFileKey, relativeEscapes } from './util.js'
11
9
 
12
10
  // Buffer.from silently drops invalid chars, so a tampered `resource:base64` could hash-spoof; require a fixed point.
13
11
  function assertCanonicalBase64(content, file) {
14
12
  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
- }
13
+ if (buf.toString('base64') !== content) throw new Error(`extract: non-canonical base64 in resource:base64 content for ${file}`)
18
14
  return buf
19
15
  }
20
16
 
21
- export function lockfileFromBundle(bundle) {
22
- const modules = new Map()
23
- for (const [dir, { files, ...info }] 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
- hashed[rel] = sha512integrity(bundle.formats.get(file) === 'resource:base64' ? assertCanonicalBase64(content, file) : content)
29
- }
30
- modules.set(dir, moduleInfo({ ...info, files: hashed }))
31
- }
32
- // Carry imports+formats across, else the derived lockfile is bytes-only and a later frozen run skips those cross-checks.
33
- return new Lockfile({
34
- config: bundle.config,
35
- entries: bundle.entries,
36
- modules,
37
- imports: bundle.imports,
38
- formats: bundle.formats,
39
- // Same file set as the bundle, so its executable list transfers as-is.
40
- executable: bundle.executable,
41
- })
17
+ export const lockfileFromBundle = (bundle) => Lockfile.fromBundle(bundle, (file, content) =>
18
+ sha512integrity(bundle.formats.get(file) === 'resource:base64' ? assertCanonicalBase64(content, file) : content))
19
+
20
+ function firstDifference(bundle, lock, path = '') {
21
+ if (bundle === lock) return null
22
+ const nested = (x) => typeof x === 'object' && x !== null
23
+ if (!nested(bundle) || !nested(lock) || Array.isArray(bundle) !== Array.isArray(lock)) {
24
+ return `${path} ${bundle === undefined ? 'is only in the lockfile' : lock === undefined ? 'is only in the bundle' : 'differs'}`
25
+ }
26
+ // Own keys only: JSON.parse makes a `__proto__` file name an own property, never the prototype.
27
+ const own = (x, key) => (Object.hasOwn(x, key) ? x[key] : undefined)
28
+ for (const key of new Set([...Object.keys(bundle), ...Object.keys(lock)])) {
29
+ const diff = firstDifference(own(bundle, key), own(lock, key), `${path}[${Array.isArray(bundle) ? key : JSON.stringify(key)}]`)
30
+ if (diff) return diff
31
+ }
32
+ return null
33
+ }
34
+
35
+ function readLockfile(lockAbs) {
36
+ try {
37
+ return Lockfile.parse(readFileSync(lockAbs, 'utf-8'))
38
+ } catch (cause) {
39
+ throw new Error(`extract: not a valid stasis lockfile: ${lockAbs}`, { cause })
40
+ }
42
41
  }
43
42
 
44
- export function extractCommand({ cwd = process.cwd(), bundleFile, output, logLabel = 'stasis-core' } = {}) {
43
+ // Nothing recorded changes, execute bits too, but a payload-free stat:* record, which content of its kind upgrades.
44
+ function addToLockfile(lockAbs, derived) {
45
+ const lock = readLockfile(lockAbs)
46
+ try {
47
+ return lock.mergeAgreeing(derived)
48
+ } catch (cause) {
49
+ throw new Error(`extract: --lock=add: the bundle conflicts with ${lockAbs}: ${cause.message}`, { cause })
50
+ }
51
+ }
52
+
53
+ // As bigints: a number can round a large Windows file id.
54
+ function fileId(path) {
55
+ const stats = statSync(path, { throwIfNoEntry: false, bigint: true })
56
+ return stats && `${stats.dev}:${stats.ino}`
57
+ }
58
+
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).
66
+ function alreadyInPlace(abs, file, content, bundleId) {
67
+ const stats = statSync(abs, { throwIfNoEntry: false, bigint: true })
68
+ if (stats === undefined) {
69
+ // A dangling symlink: the write would create its target, wherever that is.
70
+ if (lstatSync(abs, { throwIfNoEntry: false }) !== undefined) throw new Error(`extract: ${file} is a dangling symlink`)
71
+ return false
72
+ }
73
+ if (`${stats.dev}:${stats.ino}` === bundleId) throw new Error(`extract: ${file} is the bundle being extracted`)
74
+ if (!stats.isFile()) throw new Error(`extract: ${file} exists and is not a file`)
75
+ if (!readFileSync(abs).equals(Buffer.from(content))) throw new Error(`extract: ${file} exists with other content, which extract never overwrites`)
76
+ return true
77
+ }
78
+
79
+ export function extractCommand({ cwd = process.cwd(), bundleFile, output, lock: lockMode, logLabel = 'stasis-core' } = {}) {
45
80
  if (!bundleFile) throw new Error('extract: a bundle file is required')
81
+ if (lockMode !== undefined && !LOCK_MODES.has(lockMode)) {
82
+ throw new Error(`extract: lock must be one of ${[...LOCK_MODES].join(', ')} (got ${JSON.stringify(lockMode)})`)
83
+ }
46
84
  const bundleAbs = resolve(cwd, bundleFile)
47
85
  if (!existsSync(bundleAbs)) throw new Error(`extract: bundle file not found: ${bundleAbs}`)
48
86
 
49
87
  let bundle
50
88
  try {
51
- bundle = Bundle.parse(brotliDecompressSync(readFileSync(bundleAbs)).toString('utf-8'))
89
+ bundle = parseBundleBytes(readFileSync(bundleAbs))
52
90
  } catch (cause) {
53
91
  // Bundle.parse throws message-less asserts; wrap so the user learns which file failed.
54
92
  throw new Error(`extract: not a valid stasis bundle: ${bundleAbs}`, { cause })
@@ -59,53 +97,81 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, logLab
59
97
 
60
98
  const outDir = resolve(cwd, output ?? '.')
61
99
  const outPrefix = outDir === sep ? outDir : `${outDir}${sep}`
62
- const lockAbs = join(outDir, FILE_LOCK)
100
+ const lockAbs = join(outDir, LOCK_FILE)
101
+ // A file (or a dangling symlink) there holds neither a lockfile nor room for the bundle's paths.
102
+ const outStats = statSync(outDir, { throwIfNoEntry: false })
103
+ if (outStats === undefined ? lstatSync(outDir, { throwIfNoEntry: false }) !== undefined : !outStats.isDirectory()) {
104
+ throw new Error(`extract: output dir ${outDir} is not a directory`)
105
+ }
106
+ // lstat, not existsSync: a dangling symlink there is a lockfile too, so the default fails closed on it.
107
+ const lockPresent = lstatSync(lockAbs, { throwIfNoEntry: false }) !== undefined
108
+ const lock = lockMode ?? (lockPresent ? 'frozen' : 'none')
109
+ const frozen = lock === 'frozen'
110
+ if (frozen && !lockPresent) throw new Error(`extract: --lock=frozen needs ${lockAbs}`)
111
+ if (lock === 'none' && lockPresent) {
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)`)
113
+ }
114
+ if (lockPresent && !withLockfile && lock !== 'ignore') {
115
+ throw new Error(`extract: a legacy v0 bundle can not ${{ frozen: 'be checked against', add: 'be added to', replace: 'replace' }[lock]} ${lockAbs}`)
116
+ }
117
+ const merging = lock === 'add' && lockPresent
63
118
 
64
- // Plan-first: every target is validated inside outDir before any write; walk modules, not the last-wins
65
- // `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).
66
121
  const writes = []
67
122
  const targets = new Set()
68
- let executables = 0
69
123
  for (const [dir, { files }] of bundle.modules) {
70
124
  for (const [rel, content] of Object.entries(files)) {
71
- // 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).
72
126
  const key = moduleFileKey(dir, rel)
73
127
  if (bundle.formats.get(key) === 'directory') continue
74
- // The WRITE path keeps the plain join, so a non-`directory` rel === '' fails the canonical-path
75
- // 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.
76
129
  const file = dir === '.' ? rel : `${dir}/${rel}`
77
130
  if (typeof content !== 'string') throw new Error(`extract: bundle file content is not a string: ${file}`)
78
131
  const abs = resolve(outDir, file)
79
132
  const relToOut = relative(outDir, abs)
80
- // The `..` test is `../`-aware, NOT a bare startsWith('..') -- that would reject a legit `..foo` filename.
81
- if (relToOut === '..' || relToOut.startsWith(`..${sep}`) || isAbsolute(relToOut) || !abs.startsWith(outPrefix)) {
82
- throw new Error(`extract: bundle path escapes output dir: ${file}`)
83
- }
133
+ if (relativeEscapes(relToOut) || !abs.startsWith(outPrefix)) throw new Error(`extract: bundle path escapes output dir: ${file}`)
84
134
  // A non-canonical path changes under the resolve+relative round-trip; writing it desyncs tree from lockfile.
85
135
  if (relToOut !== file) throw new Error(`extract: non-canonical bundle path: ${file}`)
136
+ // No bundle Bundle.parse takes carries a stasis.lock.json, so no write lands on the lockfile.
86
137
  if (targets.has(abs)) throw new Error(`extract: duplicate bundle path: ${file}`)
87
- if (withLockfile && abs === lockAbs) {
88
- throw new Error(`extract: bundle contains ${FILE_LOCK}, which would collide with the derived lockfile`)
89
- }
90
138
  targets.add(abs)
91
- // 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.
92
140
  const exec = bundle.executable.has(key)
93
- if (exec) executables += 1
94
- writes.push([abs, bundle.formats.get(key) === 'resource:base64' ? assertCanonicalBase64(content, file) : content, exec])
141
+ writes.push({ abs, content: bundle.formats.get(key) === 'resource:base64' ? assertCanonicalBase64(content, file) : content, exec, file })
95
142
  }
96
143
  }
97
- // A planned file must not also be a parent directory of another, else the writes throw halfway through.
98
- for (const [abs] of writes) {
99
- for (let d = dirname(abs); d.length > outDir.length; d = dirname(d)) {
100
- if (targets.has(d)) {
101
- throw new Error(`extract: bundle path used as both file and directory: ${relative(outDir, d)}`)
102
- }
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)}`)
148
+ }
149
+ const writesLock = lock === 'add' || lock === 'replace'
150
+ const derived = withLockfile && (frozen || writesLock) ? lockfileFromBundle(bundle) : null
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}`)
154
+ const lockText = derived === null || frozen ? null : (merging ? addToLockfile(lockAbs, derived) : derived).serialize()
155
+
156
+ // What is already on disk is checked whole before the first write too; nor may the lockfile's land on the bundle.
157
+ const bundleId = fileId(bundleAbs)
158
+ if (lockText !== null && fileId(lockAbs) === bundleId) throw new Error(`extract: ${LOCK_FILE} is the bundle being extracted`)
159
+ const checkedDirs = new Set()
160
+ const inPlace = new Set()
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()) {
164
+ if (checkedDirs.has(d)) continue
165
+ const stats = statSync(d, { throwIfNoEntry: false })
166
+ if (stats === undefined && lstatSync(d, { throwIfNoEntry: false }) === undefined) break
167
+ if (!stats?.isDirectory()) throw new Error(`extract: ${relative(outDir, d) || '.'} is in the way of ${file}: not a directory`)
168
+ checkedDirs.add(d)
103
169
  }
170
+ if (alreadyInPlace(abs, file, content, bundleId)) inPlace.add(abs)
104
171
  }
105
- const lockText = withLockfile ? lockfileFromBundle(bundle).serialize() : null
106
172
 
107
- // Only the execute bit is attested, so only it is touched -- rw bits stay as written (never widen a 0600 target)
108
- // and setuid/setgid/sticky are cleared. Applied to every written file; 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.
109
175
  const withModes = withLockfile && canObserveExecuteBits()
110
176
  let chmodFailures = 0
111
177
  const applyMode = (abs, exec) => {
@@ -131,21 +197,28 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, logLab
131
197
  }
132
198
  }
133
199
 
134
- for (const [abs, content, exec] of writes) {
135
- mkdirSync(dirname(abs), { recursive: true })
136
- writeFileSync(abs, content)
200
+ for (const { abs, content, exec } of writes) {
201
+ if (!inPlace.has(abs)) {
202
+ mkdirSync(dirname(abs), { recursive: true })
203
+ // Exclusive: a file that appeared since the check, or one a case-insensitive disk folds onto another, fails.
204
+ writeFileSync(abs, content, { flag: 'wx' })
205
+ }
137
206
  if (withModes) applyMode(abs, exec)
138
207
  }
139
208
  mkdirSync(outDir, { recursive: true }) // for an empty bundle, where no write created it
140
- if (withLockfile) writeFileSync(lockAbs, lockText)
209
+ if (lockText !== null) writeFileSync(lockAbs, lockText)
141
210
 
142
- const execNote = executables > 0 ? ` (${executables} executable)` : ''
143
- console.warn(`[${logLabel}] Extracted ${writes.length} file(s)${execNote}${withLockfile ? ` and ${FILE_LOCK}` : ''} to ${outDir}`)
211
+ const executables = writes.filter(({ exec }) => exec).length
212
+ const notes = [executables > 0 && `${executables} executable`, inPlace.size > 0 && `${inPlace.size} already in place`].filter(Boolean)
213
+ const execNote = notes.length > 0 ? ` (${notes.join(', ')})` : ''
214
+ const andLock = lockText !== null && !merging ? ` and ${LOCK_FILE}` : ''
215
+ const lockNote = frozen ? `, verified against ${LOCK_FILE}` : merging ? `, added to ${LOCK_FILE}` : ''
216
+ console.warn(`[${logLabel}] Extracted ${writes.length} file(s)${execNote}${andLock} to ${outDir}${lockNote}`)
144
217
  if (chmodFailures > 0) {
145
218
  console.warn(`[${logLabel}] Warning: could not set file modes on ${chmodFailures} file(s) (the filesystem may not support them); contents were written`)
146
219
  }
147
- if (!withLockfile) {
148
- console.warn(`[${logLabel}] Warning: legacy v0 bundle records no package name/version, so ${FILE_LOCK} can not be restored and was not written`)
220
+ if (!withLockfile && writesLock) {
221
+ console.warn(`[${logLabel}] Warning: legacy v0 bundle records no package name/version, so ${LOCK_FILE} can not be restored and was not written`)
149
222
  }
150
- return { dir: outDir, files: writes.length, executable: executables }
223
+ return { dir: outDir, files: writes.length, executable: executables, inPlace: inPlace.size, lock }
151
224
  }