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

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.
@@ -10,15 +10,19 @@ import { assertRealPathWithinBase, hasNodeModulesSegment, relativeEscapes, split
10
10
  const utf8 = new TextDecoder()
11
11
  export const packageJSONText = (bytes) => utf8.decode(bytes)
12
12
 
13
- export function packageType(file, host = diskHost) {
13
+ // The `type` of the package.json nearest `file`, read through `kept(path, read)`, a cache by that
14
+ // package.json's path where one is given (a scan's, which reads the same one for each file under it).
15
+ export function packageType(file, host = diskHost, kept = (path, read) => read()) {
14
16
  const pkg = host.findPackageJSON(file)
15
17
  if (!pkg) return null
16
- try {
17
- const type = JSON.parse(packageJSONText(host.readFile(pkg))).type
18
- return type === 'module' || type === 'commonjs' ? type : null
19
- } catch {
20
- return null
21
- }
18
+ return kept(pkg, () => {
19
+ try {
20
+ const type = JSON.parse(packageJSONText(host.readFile(pkg))).type
21
+ return type === 'module' || type === 'commonjs' ? type : null
22
+ } catch {
23
+ return null
24
+ }
25
+ })
22
26
  }
23
27
 
24
28
  // Directories where a package keeps copies of OTHER packages, each under a package.json of its own,
@@ -126,6 +130,17 @@ export function findPackageMetadata(baseDir, fileRelPath, { strict = false, chec
126
130
  }
127
131
  }
128
132
 
133
+ // findPackageMetadata (with `options`) of each project-relative path, once per directory, the only
134
+ // thing its answer depends on.
135
+ export function packageLookup(baseDir, options) {
136
+ const byDir = new Map()
137
+ return (path) => {
138
+ const dir = posix.dirname(path)
139
+ if (!byDir.has(dir)) byDir.set(dir, findPackageMetadata(baseDir, path, options))
140
+ return byDir.get(dir)
141
+ }
142
+ }
143
+
129
144
  // The directory, package-relative, of the package.json naming `manifestName` at `dir` (project-relative,
130
145
  // POSIX) where it is a subpackage (isSubpackage) of the package at `pkgDir`; else undefined. The package's
131
146
  // own package.json is read only where the name ends in that directory.
@@ -139,6 +154,18 @@ function hostSubpackageDir(baseDir, pkgDir, dir, manifestName, options) {
139
154
  // The error codes that mean nothing is at a path.
140
155
  export const NO_ENTRY = new Set(['ENOENT', 'ENOTDIR'])
141
156
 
157
+ // Whether anything is at `p` itself, a link not followed, a broken one too (`host.readlink` throws
158
+ // when nothing is).
159
+ export function lexists(p, host) {
160
+ try {
161
+ host.readlink(p)
162
+ return true
163
+ } catch (err) {
164
+ if (NO_ENTRY.has(err.code)) return false
165
+ throw err
166
+ }
167
+ }
168
+
142
169
  // Why `file` can't be read, where `host.stat` gave null, or null when nothing is there (a missing
143
170
  // path, one through a file, a link to nothing). host.stat answers null for any failure, as Node's
144
171
  // module lookup does; real stat tells them apart: a link loop, a directory that may not be searched
@@ -162,6 +189,11 @@ export function statStrict(host, file, label) {
162
189
  throw new Error(`${label}: can't be read (${failure.code ?? failure.message})`, { cause: failure })
163
190
  }
164
191
 
192
+ // The error Node gives for a package.json at `path` that is no JSON object (`cause`: why it doesn't parse).
193
+ export const invalidPackageConfig = (path, cause) => Object.assign(
194
+ cause === undefined ? new Error(`Invalid package config ${path}.`) : new Error(`Invalid package config ${path}.`, { cause }),
195
+ { code: 'ERR_INVALID_PACKAGE_CONFIG' })
196
+
165
197
  // host.stat for a package.json, as Node's lookups read one: null when nothing is there, and one that
166
198
  // can't be read (a link loop, a directory that may not be searched) throws ERR_INVALID_PACKAGE_CONFIG,
167
199
  // as Node refuses it.
package/src/bundle.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import {
2
2
  assert,
3
3
  assertArtifactPath,
4
+ assertPayloadFree,
4
5
  canonicalFileKey,
5
6
  duplicateKeyError,
6
7
  fileSetToObject,
@@ -8,6 +9,7 @@ import {
8
9
  flatFileKeys,
9
10
  groupModules,
10
11
  hasNodeModulesSegment,
12
+ isLockfileName,
11
13
  isPlainObject,
12
14
  mergeFormatMaps,
13
15
  mergeImportMaps,
@@ -37,6 +39,12 @@ const LEGACY_VERSION = 0
37
39
 
38
40
  const duplicateKey = duplicateKeyError('bundle', 'artifact (bundle=replace)')
39
41
 
42
+ // No bundle carries a stasis lockfile: extracted, one would replace the lockfile there (the attestation a frozen
43
+ // extract checks the bundle against), or root a stasis project of its own wherever it lands.
44
+ const assertNoLockfile = (keys) => {
45
+ for (const key of keys) assert(!isLockfileName(key), `bundle: ${key} is a stasis lockfile, which no bundle may carry`)
46
+ }
47
+
40
48
  // A v0 path's bucket split; '' and '.' both spell the root listing (rel '').
41
49
  const inferModuleDir = (path) =>
42
50
  splitNodeModulesPath(path) ?? { dir: '.', rel: path === '.' ? '' : path, name: null }
@@ -143,7 +151,7 @@ export class Bundle {
143
151
  this.imports = imports ?? new Map()
144
152
  this.executable = executable ?? new Set()
145
153
  this.reason = reason
146
- this.repo = normalizeRepo(repo)
154
+ this.repo = repo
147
155
  this.package = pkg
148
156
  }
149
157
 
@@ -241,6 +249,8 @@ export class Bundle {
241
249
 
242
250
  // Flat keys must be unique across buckets: two different bucket splits can flatten to one path, and the `sources` getter would serve either payload.
243
251
  const flatKeys = flatFileKeys(modules, 'bundle', duplicateKey)
252
+ assertNoLockfile(flatKeys.keys())
253
+ assertPayloadFree(formats, flatKeys, 'bundle')
244
254
  const imports = parseImports(json.imports)
245
255
 
246
256
  if (!contents) for (const [dir, info] of modules) modules.set(dir, lockModule(dir, info))
@@ -264,7 +274,9 @@ export class Bundle {
264
274
 
265
275
  serialize() {
266
276
  // Never write an artifact that parse would reject.
267
- flatFileKeys(this.modules, 'bundle', duplicateKey)
277
+ const flatKeys = flatFileKeys(this.modules, 'bundle', duplicateKey)
278
+ assertNoLockfile(flatKeys.keys())
279
+ assertPayloadFree(this.formats, flatKeys, 'bundle')
268
280
  const { modules, sources } = groupModules(this.modules, { skipEmpty: true, what: 'bundle' })
269
281
  const full = this.config.scope === 'full'
270
282
  const data = { version: VERSION, config: this.config }
package/src/cli.js ADDED
@@ -0,0 +1,153 @@
1
+ // The commands both CLIs take, `stasis-core` and `stasis`, from their arguments: `add`, `extract` and
2
+ // `prune` whole, and `run` in steps, so `stasis run` can add its own options on top -- its options
3
+ // parsed and checked, the config the loader reads set in the environment, and the program run under
4
+ // the loader. Each names itself `label` (the CLI's name) and leaves a usage error to `fail(message)`,
5
+ // which exits.
6
+
7
+ import { spawn } from 'node:child_process'
8
+ import { once } from 'node:events'
9
+ import { constants as osConstants } from 'node:os'
10
+ import { resolve } from 'node:path'
11
+ import { parseBrotliQuality, parseLeadingOptions, valueFlagsOf } from './util.js'
12
+
13
+ const RUN_OPTIONS = {
14
+ lock: { type: 'string', default: 'none' },
15
+ bundle: { type: 'string', default: 'none' },
16
+ 'bundle-file': { type: 'string' },
17
+ 'resources-bundle-file': { type: 'string' },
18
+ debug: { type: 'boolean' },
19
+ dependencies: { type: 'boolean' },
20
+ 'child-process': { type: 'boolean' },
21
+ import: { type: 'string', multiple: true },
22
+ fs: { type: 'string' },
23
+ resources: { type: 'string' },
24
+ 'brotli-quality': { type: 'string' },
25
+ }
26
+ // `--fs` is taken only as `--fs=<mode>`: a bare `--fs` is refused rather than given the program as its mode.
27
+ const RUN_VALUE_FLAGS = ['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--import', '--resources', '--brotli-quality']
28
+
29
+ // `run`'s options, and the caller's own `options` (boolean ones), shifted off the front of `argv`,
30
+ // which keeps the program and its arguments; checked, a usage error being `fail(message)`'s (which
31
+ // exits). -> the run: `values` as parsed, and the config they set.
32
+ export function parseRunOptions(argv, { options = {}, fail }) {
33
+ const values = parseLeadingOptions(argv, { ...RUN_OPTIONS, ...options }, { valueFlags: RUN_VALUE_FLAGS, onError: fail })
34
+ if (argv.length === 0) fail('Nothing to run: no path to file given')
35
+ const { lock, bundle } = values
36
+ if (!['none', 'ignore', 'add', 'replace', 'frozen'].includes(lock)) fail('Error: invalid --lock value')
37
+ const bundleFile = values['bundle-file'] ? resolve(values['bundle-file']) : ''
38
+ const resourcesBundleFile = values['resources-bundle-file'] ? resolve(values['resources-bundle-file']) : ''
39
+ if (!['none', 'ignore', 'add', 'replace', 'load', 'frozen'].includes(bundle)) fail('Error: invalid --bundle value')
40
+ if (bundleFile && bundle === 'none') fail('Error: --bundle-file requires --bundle=(add|replace|load|frozen|ignore)')
41
+ // --resources-bundle-file needs an active bundle mode (unlike --bundle-file, inert under ignore).
42
+ if (resourcesBundleFile && (bundle === 'none' || bundle === 'ignore')) fail('Error: --resources-bundle-file requires --bundle=(add|replace|load|frozen)')
43
+ if (bundle === 'load' && lock !== 'frozen' && lock !== 'none' && lock !== 'ignore') fail('Error: --bundle=load is incompatible with --lock=(add|replace)')
44
+ if (lock === 'none' && bundle === 'none') fail('Error: stasis needs a lockfile or a bundle: set --lock or --bundle')
45
+ // --fs requires a bundle mode (add|replace|load); `sync` patches the sync fs readers,
46
+ // `async` adds their callback + fs.promises counterparts on top.
47
+ if (values.fs !== undefined && !['sync', 'async'].includes(values.fs)) fail("Error: --fs must be 'sync' or 'async'")
48
+ if (values.fs !== undefined && !['add', 'replace', 'load'].includes(bundle)) fail('Error: --fs requires --bundle=(add|replace|load)')
49
+ const brotliQuality = brotliQualityOption(values['brotli-quality'], fail)
50
+ // --import: extra preload module(s) passed through to the spawned node. Node resolves each
51
+ // against the project cwd; they ride AFTER stasis's own loader import.
52
+ const imports = values.import ?? []
53
+ if (imports.some((s) => s === '')) fail('Error: --import requires a module specifier (e.g. --import=./instrument.mjs)')
54
+ return {
55
+ values,
56
+ lock,
57
+ scope: values.dependencies ? 'node_modules' : 'full',
58
+ bundle,
59
+ bundleFile,
60
+ resourcesBundleFile,
61
+ debug: values.debug ? '1' : '',
62
+ // --child-process: forward forked-child (e.g. Metro worker) capture to the root via per-pid shards.
63
+ childProcess: values['child-process'] ? '1' : '',
64
+ fs: values.fs ?? '',
65
+ // --resources: comma-separated extension/filename allowlist for `--fs` captures.
66
+ resources: values.resources ?? '',
67
+ brotliQuality,
68
+ imports,
69
+ }
70
+ }
71
+
72
+ // The `--brotli-quality` given as `value`, a usage error where it's no quality. -> it, or undefined
73
+ export function brotliQualityOption(value, fail) {
74
+ if (value === undefined) return undefined
75
+ try {
76
+ return parseBrotliQuality('--brotli-quality', value)
77
+ } catch (cause) {
78
+ return fail(`Error: ${cause.message}`)
79
+ }
80
+ }
81
+
82
+ // Sets the environment variable `name` to `value` (a string), refusing one the environment already
83
+ // sets otherwise.
84
+ export function setEnv(name, value) {
85
+ const env = process.env[name]
86
+ if (env && env !== value) throw new Error(`env conflict: ${name}="${env}", effective: "${value}"`)
87
+ process.env[name] = value
88
+ }
89
+
90
+ // Announces `run` on stderr as `label` (the CLI's name), with the caller's own `extra` config after
91
+ // childProcess, and sets it in the environment the loader reads it from.
92
+ export function setRunEnv(label, run, extra = {}) {
93
+ const { lock, scope, bundle, bundleFile, resourcesBundleFile, debug, childProcess, fs, resources, brotliQuality, imports } = run
94
+ console.warn(`[${label}] Running stasis with config:`, { lock, scope, bundle, ...(bundleFile && { bundleFile }), ...(resourcesBundleFile && { resourcesBundleFile }), ...(childProcess && { childProcess: true }), ...extra, ...(imports.length > 0 && { import: imports }), ...(fs && { fs }), ...(resources && { resources }), ...(brotliQuality !== undefined && { brotliQuality }) })
95
+ if (debug) console.warn(`[${label}] Warning: stasis debug mode active`)
96
+ setEnv('EXODUS_STASIS_LOCK', lock)
97
+ setEnv('EXODUS_STASIS_SCOPE', scope)
98
+ setEnv('EXODUS_STASIS_BUNDLE', bundle)
99
+ setEnv('EXODUS_STASIS_BUNDLE_FILE', bundleFile)
100
+ setEnv('EXODUS_STASIS_RESOURCES_BUNDLE_FILE', resourcesBundleFile)
101
+ setEnv('EXODUS_STASIS_DEBUG', debug)
102
+ setEnv('EXODUS_STASIS_CHILD_PROCESS', childProcess)
103
+ setEnv('EXODUS_STASIS_FS', fs)
104
+ setEnv('EXODUS_STASIS_RESOURCES', resources)
105
+ // Only set when given: an unconditional setEnv('') would reject an ambient EXODUS_STASIS_BROTLI_QUALITY as a conflict.
106
+ if (brotliQuality !== undefined) setEnv('EXODUS_STASIS_BROTLI_QUALITY', String(brotliQuality))
107
+ }
108
+
109
+ // Runs the program `argv` in a node taking `nodeArgs`, then `--import`ing `loader` (a URL) and the
110
+ // run's `imports`. Those preloads ride after the loader, so they evaluate under its hooks; their
111
+ // module graphs pass through uncaptured unless the app graph reaches them -- then they're promoted
112
+ // into the capture (see hooks.js). Exits as the program does: its code, or 128+signo when a signal
113
+ // killed it (the shell's convention) instead of the implicit 0.
114
+ export async function runProgram(argv, { nodeArgs = [], loader, imports }) {
115
+ const args = [...nodeArgs, '--import', loader, ...imports.flatMap((specifier) => ['--import', specifier]), ...argv]
116
+ const child = spawn(process.execPath, args, { stdio: 'inherit' })
117
+ const [code, signal] = await once(child, 'close')
118
+ process.exitCode = code ?? 128 + (osConstants.signals[signal] ?? 0)
119
+ }
120
+
121
+ // `add`: packs the listed files (no resolver), taking split targets + resource allowlist from
122
+ // stasis.config.json; it takes no flags. Its runtime errors propagate as they are: wrapping them in
123
+ // fail() would bury the cause.
124
+ export async function addCli(argv, { label, fail }) {
125
+ if (argv.length === 0) fail('Nothing to add: no file given')
126
+ if (argv.some((a) => a.startsWith('-'))) fail('Error: add takes no options; its targets and resource allowlist come from stasis.config.json')
127
+ const { addCommand } = await import('./add.js')
128
+ addCommand({ cwd: process.cwd(), entries: argv, logLabel: label })
129
+ }
130
+
131
+ // `extract`: a bundle's files written out, as `--output` and `--lock` say.
132
+ export async function extractCli(argv, { label, fail }) {
133
+ const options = {
134
+ output: { type: 'string', short: 'o' },
135
+ lock: { type: 'string' },
136
+ }
137
+ const values = parseLeadingOptions(argv, options, { valueFlags: valueFlagsOf(options), onError: fail })
138
+ if (argv.length === 0) fail('Nothing to extract: no bundle file given')
139
+ if (argv.length > 1) fail('Error: extract takes exactly one bundle file')
140
+ // Unset: frozen when the output dir holds a stasis.lock.json, else none (see extractCommand).
141
+ if (values.lock !== undefined && !['frozen', 'add', 'replace', 'ignore', 'none'].includes(values.lock)) fail('Error: invalid --lock value')
142
+ const { extractCommand } = await import('./extract.js')
143
+ extractCommand({ cwd: process.cwd(), bundleFile: argv[0], output: values.output, lock: values.lock, logLabel: label })
144
+ }
145
+
146
+ // `prune`: the project's node_modules (the one given, else the cwd's) cut down to its lockfile.
147
+ export async function pruneCli(argv, { label, fail }) {
148
+ if (argv.length > 1) fail('Error: prune takes at most one path argument')
149
+ const root = argv[0] ? resolve(argv[0]) : process.cwd()
150
+ const { prune } = await import('./prune.js')
151
+ const { removed, validated, minimized } = prune({ root })
152
+ console.warn(`[${label}] prune: validated ${validated.length} file(s), removed ${removed.length} file(s), minimized ${minimized.length} package.json file(s)`)
153
+ }
package/src/config.js CHANGED
@@ -2,7 +2,7 @@ import assert from 'node:assert/strict'
2
2
 
3
3
  import { diskHost } from './host.js'
4
4
  import { canonicalizePath } from './state-util.js'
5
- import { extSetsEqual, isBrotliQuality, parseBrotliQuality, parseExtraOption, parseResourcesOption } from './util.js'
5
+ import { extSetsEqual, isBrotliQuality, parseBrotliQuality, parseExtraOption, parseGeneratePrisma, parseInstallDevDependencies, parseLazyDependencies, parseResourcesOption } from './util.js'
6
6
 
7
7
  export const DEFAULT_LOCK = 'add'
8
8
  export const DEFAULT_BUNDLE = 'none'
@@ -21,8 +21,9 @@ const envList = (value) => value.split(',').map((s) => s.trim()).filter(Boolean)
21
21
  // Every option: its env var, how the env string parses (strings pass through) and, for a non-string
22
22
  // option, how a `new Config()` option does. `lockFile` and `bundle` are flag/env-only (never from
23
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), and `entries` is `stasis bundle`'s, which a run
25
- // takes nothing from.
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.
26
27
  const OPTIONS = {
27
28
  scope: { env: 'EXODUS_STASIS_SCOPE', valid: new Set(['node_modules', 'full']) },
28
29
  lock: { env: 'EXODUS_STASIS_LOCK', valid: new Set(['none', 'ignore', 'add', 'replace', 'frozen']) },
@@ -39,7 +40,9 @@ const OPTIONS = {
39
40
  resources: { env: 'EXODUS_STASIS_RESOURCES', parse: (name, value) => parseResourcesOption('env', envList(value)), option: (value) => parseResourcesOption('options', value) },
40
41
  }
41
42
  const OPTION_KEYS = Object.keys(OPTIONS)
42
- const CONFIG_FILE_KEYS = [...OPTION_KEYS.filter((key) => key !== 'lockFile' && key !== 'bundle'), 'extra', 'entries']
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)]
43
46
  // The one mode a stasis.config.json can pin: a run that writes, loads or ignores is given its modes
44
47
  // explicitly (flags, env, options), never by a file.
45
48
  const CONFIG_FILE_LOCK = 'frozen'
@@ -214,6 +217,11 @@ export class Config {
214
217
  for (const key of keys) {
215
218
  // `stasis bundle`'s, validated there.
216
219
  if (key === 'entries') continue
220
+ // 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
+ }
217
225
  if (key === 'resources') this.#opts.resources = parseResourcesOption('stasis.config.json', config.resources)
218
226
  else if (key === 'extra') this.#opts.extra = parseExtraOption('stasis.config.json', config.extra)
219
227
  // '' -> undefined like the constructor: otherwise canonicalizePath('') claims cwd as a write target.
package/src/extract.js CHANGED
@@ -1,13 +1,14 @@
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'
8
+ import { EXECUTE_BITS, canObserveExecuteBits, moduleFileKey, moduleFileKeys, relativeEscapes } from './util.js'
9
9
 
10
10
  const FILE_LOCK = 'stasis.lock.json'
11
+ const LOCK_MODES = new Set(['frozen', 'add', 'replace', 'ignore', 'none'])
11
12
 
12
13
  // Buffer.from silently drops invalid chars, so a tampered `resource:base64` could hash-spoof; require a fixed point.
13
14
  function assertCanonicalBase64(content, file) {
@@ -18,37 +19,94 @@ function assertCanonicalBase64(content, file) {
18
19
  return buf
19
20
  }
20
21
 
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)
22
+ // Hashes the raw on-disk bytes, so decodes 'resource:base64' back first.
23
+ export const lockfileFromBundle = (bundle) => Lockfile.fromBundle(bundle, (file, content) =>
24
+ sha512integrity(bundle.formats.get(file) === 'resource:base64' ? assertCanonicalBase64(content, file) : content))
25
+
26
+ // Where two parsed JSON values first differ, as a path into them, or null when they are equal.
27
+ function firstDifference(bundle, lock, path = '') {
28
+ if (bundle === lock) return null
29
+ const nested = (x) => typeof x === 'object' && x !== null
30
+ if (!nested(bundle) || !nested(lock) || Array.isArray(bundle) !== Array.isArray(lock)) {
31
+ return `${path} ${bundle === undefined ? 'is only in the lockfile' : lock === undefined ? 'is only in the bundle' : 'differs'}`
32
+ }
33
+ // Own keys only: JSON.parse makes a `__proto__` file name an own property, never the prototype.
34
+ const own = (x, key) => (Object.hasOwn(x, key) ? x[key] : undefined)
35
+ for (const key of new Set([...Object.keys(bundle), ...Object.keys(lock)])) {
36
+ const diff = firstDifference(own(bundle, key), own(lock, key), `${path}[${Array.isArray(bundle) ? key : JSON.stringify(key)}]`)
37
+ if (diff) return diff
38
+ }
39
+ return null
40
+ }
41
+
42
+ function readLockfile(lockAbs) {
43
+ try {
44
+ return Lockfile.parse(readFileSync(lockAbs, 'utf-8'))
45
+ } catch (cause) {
46
+ throw new Error(`extract: not a valid stasis lockfile: ${lockAbs}`, { cause })
47
+ }
48
+ }
49
+
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.
60
+ function addToLockfile(lockAbs, derived) {
61
+ const lock = readLockfile(lockAbs)
62
+ let merged
63
+ try {
64
+ merged = lock.merge(derived)
65
+ } catch (cause) {
66
+ throw new Error(`extract: --lock=add: the bundle conflicts with ${lockAbs}: ${cause.message}`, { cause })
67
+ }
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`)
29
73
  }
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
- })
74
+ }
75
+ return merged
76
+ }
77
+
78
+ // A file's device and inode (as bigints: a number can round a large Windows file id), undefined when there's none.
79
+ function fileId(path) {
80
+ const stats = statSync(path, { throwIfNoEntry: false, bigint: true })
81
+ return stats && `${stats.dev}:${stats.ino}`
82
+ }
83
+
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).
86
+ function alreadyInPlace(abs, file, content, bundleId) {
87
+ const stats = statSync(abs, { throwIfNoEntry: false, bigint: true })
88
+ if (stats === undefined) {
89
+ // A dangling symlink: the write would create its target, wherever that is.
90
+ if (lstatSync(abs, { throwIfNoEntry: false }) !== undefined) throw new Error(`extract: ${file} is a dangling symlink`)
91
+ return false
92
+ }
93
+ if (`${stats.dev}:${stats.ino}` === bundleId) throw new Error(`extract: ${file} is the bundle being extracted`)
94
+ if (!stats.isFile()) throw new Error(`extract: ${file} exists and is not a file`)
95
+ if (!readFileSync(abs).equals(Buffer.from(content))) throw new Error(`extract: ${file} exists with other content, which extract never overwrites`)
96
+ return true
42
97
  }
43
98
 
44
- export function extractCommand({ cwd = process.cwd(), bundleFile, output, logLabel = 'stasis-core' } = {}) {
99
+ export function extractCommand({ cwd = process.cwd(), bundleFile, output, lock: lockMode, logLabel = 'stasis-core' } = {}) {
45
100
  if (!bundleFile) throw new Error('extract: a bundle file is required')
101
+ if (lockMode !== undefined && !LOCK_MODES.has(lockMode)) {
102
+ throw new Error(`extract: lock must be one of ${[...LOCK_MODES].join(', ')} (got ${JSON.stringify(lockMode)})`)
103
+ }
46
104
  const bundleAbs = resolve(cwd, bundleFile)
47
105
  if (!existsSync(bundleAbs)) throw new Error(`extract: bundle file not found: ${bundleAbs}`)
48
106
 
49
107
  let bundle
50
108
  try {
51
- bundle = Bundle.parse(brotliDecompressSync(readFileSync(bundleAbs)).toString('utf-8'))
109
+ bundle = parseBundleBytes(readFileSync(bundleAbs))
52
110
  } catch (cause) {
53
111
  // Bundle.parse throws message-less asserts; wrap so the user learns which file failed.
54
112
  throw new Error(`extract: not a valid stasis bundle: ${bundleAbs}`, { cause })
@@ -60,6 +118,25 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, logLab
60
118
  const outDir = resolve(cwd, output ?? '.')
61
119
  const outPrefix = outDir === sep ? outDir : `${outDir}${sep}`
62
120
  const lockAbs = join(outDir, FILE_LOCK)
121
+ // A file (or a dangling symlink) there holds neither a lockfile nor room for the bundle's paths.
122
+ const outStats = statSync(outDir, { throwIfNoEntry: false })
123
+ if (outStats === undefined ? lstatSync(outDir, { throwIfNoEntry: false }) !== undefined : !outStats.isDirectory()) {
124
+ throw new Error(`extract: output dir ${outDir} is not a directory`)
125
+ }
126
+ // lstat, not existsSync: a dangling symlink there is a lockfile too, so the default fails closed on it.
127
+ const lockPresent = lstatSync(lockAbs, { throwIfNoEntry: false }) !== undefined
128
+ // Unset: assert the lockfile already in the output dir, else write none.
129
+ const lock = lockMode ?? (lockPresent ? 'frozen' : 'none')
130
+ const frozen = lock === 'frozen'
131
+ if (frozen && !lockPresent) throw new Error(`extract: --lock=frozen needs ${lockAbs}`)
132
+ if (lock === 'none' && lockPresent) {
133
+ 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
+ }
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
+ if (lockPresent && !withLockfile && lock !== 'ignore') {
137
+ throw new Error(`extract: a legacy v0 bundle can not ${{ frozen: 'be checked against', add: 'be added to', replace: 'replace' }[lock]} ${lockAbs}`)
138
+ }
139
+ const merging = lock === 'add' && lockPresent
63
140
 
64
141
  // Plan-first: every target is validated inside outDir before any write; walk modules, not the last-wins
65
142
  // `sources` getter. Containment is lexical -- symlinks are followed, so untrusted bundles need a fresh dir (doc/extract.md).
@@ -77,21 +154,19 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, logLab
77
154
  if (typeof content !== 'string') throw new Error(`extract: bundle file content is not a string: ${file}`)
78
155
  const abs = resolve(outDir, file)
79
156
  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)) {
157
+ // relativeEscapes is `../`-aware, NOT a bare startsWith('..') -- that would reject a legit `..foo` filename.
158
+ if (relativeEscapes(relToOut) || !abs.startsWith(outPrefix)) {
82
159
  throw new Error(`extract: bundle path escapes output dir: ${file}`)
83
160
  }
84
161
  // A non-canonical path changes under the resolve+relative round-trip; writing it desyncs tree from lockfile.
85
162
  if (relToOut !== file) throw new Error(`extract: non-canonical bundle path: ${file}`)
163
+ // No bundle Bundle.parse takes carries a stasis.lock.json, so no write lands on the lockfile.
86
164
  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
165
  targets.add(abs)
91
166
  // Executability rides the plan tuple, so the chmod can only ever reach a file we actually wrote.
92
167
  const exec = bundle.executable.has(key)
93
168
  if (exec) executables += 1
94
- writes.push([abs, bundle.formats.get(key) === 'resource:base64' ? assertCanonicalBase64(content, file) : content, exec])
169
+ writes.push([abs, bundle.formats.get(key) === 'resource:base64' ? assertCanonicalBase64(content, file) : content, exec, file])
95
170
  }
96
171
  }
97
172
  // A planned file must not also be a parent directory of another, else the writes throw halfway through.
@@ -102,10 +177,35 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, logLab
102
177
  }
103
178
  }
104
179
  }
105
- const lockText = withLockfile ? lockfileFromBundle(bundle).serialize() : null
180
+ // Only add and replace write a lockfile, and frozen checks one; each before the first write.
181
+ const writesLock = lock === 'add' || lock === 'replace'
182
+ const derived = withLockfile && (frozen || writesLock) ? lockfileFromBundle(bundle) : null
183
+ if (frozen) assertLockfileMatches(lockAbs, derived)
184
+ const lockText = derived === null || frozen ? null : (merging ? addToLockfile(lockAbs, derived) : derived).serialize()
185
+
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.
189
+ const bundleId = fileId(bundleAbs)
190
+ if (lockText !== null && fileId(lockAbs) === bundleId) throw new Error(`extract: ${FILE_LOCK} is the bundle being extracted`)
191
+ const checkedDirs = new Set()
192
+ 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()) {
198
+ if (checkedDirs.has(d)) continue
199
+ const stats = statSync(d, { throwIfNoEntry: false })
200
+ if (stats === undefined && lstatSync(d, { throwIfNoEntry: false }) === undefined) break
201
+ if (!stats?.isDirectory()) throw new Error(`extract: ${relative(outDir, d) || '.'} is in the way of ${file}: not a directory`)
202
+ checkedDirs.add(d)
203
+ }
204
+ if (alreadyInPlace(abs, file, content, bundleId)) inPlace.add(abs)
205
+ }
106
206
 
107
207
  // 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.
208
+ // and setuid/setgid/sticky are cleared. Applied to every extracted file, one already in place too; skipped for v0, which attests no modes.
109
209
  const withModes = withLockfile && canObserveExecuteBits()
110
210
  let chmodFailures = 0
111
211
  const applyMode = (abs, exec) => {
@@ -132,20 +232,27 @@ export function extractCommand({ cwd = process.cwd(), bundleFile, output, logLab
132
232
  }
133
233
 
134
234
  for (const [abs, content, exec] of writes) {
135
- mkdirSync(dirname(abs), { recursive: true })
136
- writeFileSync(abs, content)
235
+ if (!inPlace.has(abs)) {
236
+ 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.
239
+ writeFileSync(abs, content, { flag: 'wx' })
240
+ }
137
241
  if (withModes) applyMode(abs, exec)
138
242
  }
139
243
  mkdirSync(outDir, { recursive: true }) // for an empty bundle, where no write created it
140
- if (withLockfile) writeFileSync(lockAbs, lockText)
244
+ if (lockText !== null) writeFileSync(lockAbs, lockText)
141
245
 
142
- const execNote = executables > 0 ? ` (${executables} executable)` : ''
143
- console.warn(`[${logLabel}] Extracted ${writes.length} file(s)${execNote}${withLockfile ? ` and ${FILE_LOCK}` : ''} to ${outDir}`)
246
+ const notes = [executables > 0 && `${executables} executable`, inPlace.size > 0 && `${inPlace.size} already in place`].filter(Boolean)
247
+ 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}` : ''
250
+ console.warn(`[${logLabel}] Extracted ${writes.length} file(s)${execNote}${andLock} to ${outDir}${lockNote}`)
144
251
  if (chmodFailures > 0) {
145
252
  console.warn(`[${logLabel}] Warning: could not set file modes on ${chmodFailures} file(s) (the filesystem may not support them); contents were written`)
146
253
  }
147
- if (!withLockfile) {
254
+ if (!withLockfile && writesLock) {
148
255
  console.warn(`[${logLabel}] Warning: legacy v0 bundle records no package name/version, so ${FILE_LOCK} can not be restored and was not written`)
149
256
  }
150
- return { dir: outDir, files: writes.length, executable: executables }
257
+ return { dir: outDir, files: writes.length, executable: executables, inPlace: inPlace.size, lock }
151
258
  }
package/src/fs.js CHANGED
@@ -8,7 +8,7 @@ import { createRequire, syncBuiltinESMExports } from 'node:module'
8
8
  import { resolve } from 'node:path'
9
9
  import { fileURLToPath, pathToFileURL } from 'node:url'
10
10
 
11
- import { realReadFileSync } from './state-util.js'
11
+ import { realContained, realReadFileSync } from './state-util.js'
12
12
  import { isDotEnvFile, isPathWithin, isStasisArtifactName } from './util.js'
13
13
 
14
14
  const require = createRequire(import.meta.url)
@@ -40,24 +40,6 @@ function toAbsPath(path) {
40
40
  return null
41
41
  }
42
42
 
43
- let realRootCache
44
- function realRootOf(root) {
45
- if (realRootCache?.root !== root) {
46
- let real
47
- try { real = realRealpathSync(root) } catch { real = root }
48
- realRootCache = { root, real }
49
- }
50
- return realRootCache.real
51
- }
52
-
53
- // Capture-side containment: the path's REAL location must stay inside root's real path, else an
54
- // in-tree symlink pointing OUT would pull external content into the signed bundle.
55
- function realContained(root, abs) {
56
- let real
57
- try { real = realRealpathSync(abs) } catch { return false }
58
- return isPathWithin(realRootOf(root), real)
59
- }
60
-
61
43
  // At the project root, drop stasis's own artifacts from the RECORDED listing so it doesn't depend on
62
44
  // whether an earlier run left them behind; the program still receives the true on-disk `names`.
63
45
  function dirCaptureNames(root, abs, names) {