@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.
- package/bin/stasis-core.js +9 -98
- package/package.json +4 -2
- package/src/add.js +75 -74
- package/src/artifact-util.js +48 -21
- package/src/brotli.js +23 -3
- package/src/bundle-util.js +39 -7
- package/src/bundle.js +14 -2
- package/src/cli.js +153 -0
- package/src/config.js +12 -4
- package/src/extract.js +148 -41
- package/src/fs.js +1 -19
- package/src/hooks.js +4 -3
- package/src/host.js +12 -1
- package/src/lockfile.js +15 -1
- package/src/state-util.js +44 -0
- package/src/state.js +99 -130
- package/src/util.js +53 -70
package/src/bundle-util.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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 =
|
|
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),
|
|
25
|
-
//
|
|
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
|
-
|
|
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,
|
|
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,
|
|
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
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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 =
|
|
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
|
-
//
|
|
81
|
-
if (
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
136
|
-
|
|
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 (
|
|
244
|
+
if (lockText !== null) writeFileSync(lockAbs, lockText)
|
|
141
245
|
|
|
142
|
-
const
|
|
143
|
-
|
|
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) {
|