@exodus/stasis-core 1.0.0-beta.8 → 1.0.0-rc.0

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.
@@ -1,13 +1,10 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- import { spawn } from 'node:child_process'
4
- import { once } from 'node:events'
5
3
  import { fileURLToPath } from 'node:url'
6
- import { basename, resolve } from 'node:path'
4
+ import { basename } from 'node:path'
7
5
  import { existsSync, realpathSync } from 'node:fs'
8
- import { constants as osConstants } from 'node:os'
9
6
  import assert from 'node:assert/strict'
10
- import { parseBrotliQuality, parseLeadingOptions } from '../src/util.js'
7
+ import { addCli, extractCli, parseRunOptions, pruneCli, runProgram, setRunEnv } from '../src/cli.js'
11
8
  import pkg from '../package.json' with { type: 'json' }
12
9
 
13
10
  const argv = [...process.argv]
@@ -18,28 +15,26 @@ const jsname = argv.shift()
18
15
  const pathsEqual = (a, b) => a === b || (existsSync(a) && realpathSync(a) === b)
19
16
  assert(basename(jsname) === 'stasis-core' || pathsEqual(jsname, fileURLToPath(import.meta.url)))
20
17
 
21
- function usage(prefix = '') {
22
- console.error(`${prefix}\nUsage:
18
+ const HELP = `Usage:
23
19
  stasis-core run --lock=(add|replace|frozen|ignore) [--bundle=(add|replace|load|frozen|ignore)] [--bundle-file=path/to/bundle.br] [--resources-bundle-file=path/to/resources.br] [--dependencies] [--child-process] [--import=module ...] [--fs=(sync|async)] [--resources=ext,ext] [--brotli-quality=0..11] path/to/file.js ...
24
- (--import forwards extra preload modules (repeatable) to the node process running the entry,
25
- e.g. --import=./instrument.mjs for a setup/instrumentation preload; a preload's own module
26
- graph is runner infrastructure like stasis's loader itself, so it stays out of the
27
- lockfile/bundle -- except modules the app graph also reaches, which are attested like any
28
- other app code)
29
20
  stasis-core add path/to/(file|dir) ...
30
- (adds the listed files to the project's bundle(s) with no dependency resolution;
31
- a directory expands to its files. Requires a stasis.config.json (all fields optional).)
32
- stasis-core extract [--output=path/to/dir] path/to/bundle.stasis.code.br
33
- (unpacks a stasis.code.br bundle back onto disk and derives a matching stasis.lock.json.)
21
+ stasis-core extract [--output=path/to/dir] [--lock=(frozen|add|replace|ignore|none)] path/to/bundle.stasis.code.br
34
22
  stasis-core prune [path/to/project]
35
- `.trim())
36
- process.exit(1)
23
+ stasis-core --version
24
+
25
+ Each command's options: https://github.com/PreventiveMeasures/stasis/blob/main/doc/<command>.md
26
+ (run, extract, prune; add is in bundle.md)`
27
+
28
+ // The help, on stderr. Exits 0 when asked for (--help), 1 when printed for want of a command.
29
+ function usage(asked = false) {
30
+ console.error(HELP)
31
+ process.exit(asked ? 0 : 1)
37
32
  }
38
33
 
39
- function setEnv(name, value) {
40
- const env = process.env[name]
41
- if (env && env !== value) throw new Error(`env conflict: ${name}="${env}", effective: "${value}"`)
42
- process.env[name] = value === undefined ? '' : value
34
+ // A usage error: the message and where the help is, never the help itself.
35
+ function fail(message) {
36
+ console.error(`${message}\nRun 'stasis-core --help' for usage.`)
37
+ process.exit(1)
43
38
  }
44
39
 
45
40
  const command = argv.shift()
@@ -47,96 +42,20 @@ const command = argv.shift()
47
42
  if (command === '-v' || command === '--version') {
48
43
  console.log(`v${pkg.version}`)
49
44
  process.exit(0)
45
+ } else if (command === '-h' || command === '--help') {
46
+ usage(true)
50
47
  } else if (command === 'run') {
51
- const options = {
52
- lock: { type: 'string', default: 'none' },
53
- bundle: { type: 'string', default: 'none' },
54
- 'bundle-file': { type: 'string' },
55
- 'resources-bundle-file': { type: 'string' },
56
- debug: { type: 'boolean' },
57
- dependencies: { type: 'boolean' },
58
- 'child-process': { type: 'boolean' },
59
- import: { type: 'string', multiple: true },
60
- fs: { type: 'string' },
61
- resources: { type: 'string' },
62
- 'brotli-quality': { type: 'string' },
63
- }
64
- const values = parseLeadingOptions(argv, options, {
65
- valueFlags: ['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--import', '--resources', '--brotli-quality'],
66
- onError: usage,
67
- })
68
- if (argv.length === 0) usage('Nothing to run: no path to file given')
69
- if (!['none', 'ignore', 'add', 'replace', 'frozen'].includes(values.lock)) usage('Error: invalid --lock value')
70
- const lock = values.lock
71
- const scope = values.dependencies ? 'node_modules' : 'full'
72
- const bundle = values.bundle
73
- const bundleFile = values['bundle-file'] ? resolve(values['bundle-file']) : ''
74
- const resourcesBundleFile = values['resources-bundle-file'] ? resolve(values['resources-bundle-file']) : ''
75
- const debug = values.debug ? '1' : ''
76
- if (!['none', 'ignore', 'add', 'replace', 'load', 'frozen'].includes(bundle)) usage('Error: invalid --bundle value')
77
- if (bundleFile && bundle === 'none') usage('Error: --bundle-file requires --bundle=(add|replace|load|frozen|ignore)')
78
- if (resourcesBundleFile && (bundle === 'none' || bundle === 'ignore')) usage('Error: --resources-bundle-file requires --bundle=(add|replace|load|frozen)')
79
- if (bundle === 'load' && lock !== 'frozen' && lock !== 'none' && lock !== 'ignore') usage('Error: --bundle=load is incompatible with --lock=(add|replace)')
80
- if (lock === 'none' && bundle === 'none') usage('Error: stasis needs a lockfile or a bundle: set --lock or --bundle')
81
- if (values.fs !== undefined && !['sync', 'async'].includes(values.fs)) usage("Error: --fs must be 'sync' or 'async'")
82
- if (values.fs !== undefined && !['add', 'replace', 'load'].includes(bundle)) usage('Error: --fs requires --bundle=(add|replace|load)')
83
- const captureFs = values.fs ?? ''
84
- const resources = values.resources ?? ''
85
- let brotliQuality
86
- if (values['brotli-quality'] !== undefined) {
87
- try {
88
- brotliQuality = parseBrotliQuality('--brotli-quality', values['brotli-quality'])
89
- } catch (cause) {
90
- usage(`Error: ${cause.message}`)
91
- }
92
- }
93
- const childProcess = values['child-process'] ? '1' : ''
94
- // --import: extra preload module(s) passed through to the spawned node. Node resolves each
95
- // against the project cwd; they ride AFTER stasis's own loader import.
96
- const imports = values.import ?? []
97
- if (imports.some((s) => s === '')) usage('Error: --import requires a module specifier (e.g. --import=./instrument.mjs)')
98
- console.warn('[stasis-core] Running stasis with config:', { lock, scope, bundle, ...(bundleFile && { bundleFile }), ...(resourcesBundleFile && { resourcesBundleFile }), ...(childProcess && { childProcess: true }), ...(imports.length > 0 && { import: imports }), ...(values.fs && { fs: values.fs }), ...(resources && { resources }), ...(brotliQuality !== undefined && { brotliQuality }) })
99
- if (debug) console.warn(`[stasis-core] Warning: stasis debug mode active`)
100
- setEnv('EXODUS_STASIS_LOCK', lock)
101
- setEnv('EXODUS_STASIS_SCOPE', scope)
102
- setEnv('EXODUS_STASIS_BUNDLE', bundle)
103
- setEnv('EXODUS_STASIS_BUNDLE_FILE', bundleFile)
104
- setEnv('EXODUS_STASIS_RESOURCES_BUNDLE_FILE', resourcesBundleFile)
105
- setEnv('EXODUS_STASIS_DEBUG', debug)
106
- setEnv('EXODUS_STASIS_CHILD_PROCESS', childProcess)
107
- setEnv('EXODUS_STASIS_FS', captureFs)
108
- setEnv('EXODUS_STASIS_RESOURCES', resources)
109
- // Only set when given: an unconditional setEnv('') would reject an ambient EXODUS_STASIS_BROTLI_QUALITY as a conflict.
110
- if (brotliQuality !== undefined) setEnv('EXODUS_STASIS_BROTLI_QUALITY', String(brotliQuality))
111
- const nodeArgs = ['--import', import.meta.resolve('../src/loader.js')]
112
- // Passthrough preloads ride after the loader, so they evaluate under its hooks; their module
113
- // graphs pass through uncaptured unless the app graph reaches them -- then they're promoted
114
- // into the capture (see src/hooks.js).
115
- for (const specifier of imports) nodeArgs.push('--import', specifier)
116
- const child = spawn(process.execPath, [...nodeArgs, ...argv], { stdio: 'inherit' })
117
- const [code, signal] = await once(child, 'close')
118
- // code is null when the child died from a signal; report 128+signo (shell convention) instead of the implicit 0
119
- process.exitCode = code ?? 128 + (osConstants.signals[signal] ?? 0)
48
+ const run = parseRunOptions(argv, { fail })
49
+ setRunEnv('stasis-core', run)
50
+ await runProgram(argv, { loader: import.meta.resolve('../src/loader.js'), imports: run.imports })
120
51
  } else if (command === 'prune') {
121
- if (argv.length > 1) usage('Error: prune takes at most one path argument')
122
- const root = argv[0] ? resolve(argv[0]) : process.cwd()
123
- const { prune } = await import('../src/prune.js')
124
- const { removed, validated, minimized } = prune({ root })
125
- console.warn(`[stasis-core] prune: validated ${validated.length} file(s), removed ${removed.length} file(s), minimized ${minimized.length} package.json file(s)`)
52
+ await pruneCli(argv, { label: 'stasis-core', fail })
126
53
  } else if (command === 'add') {
127
- if (argv.length === 0) usage('Nothing to add: no file given')
128
- if (argv.some((a) => a.startsWith('-'))) usage('Error: add takes no options; its targets and resource allowlist come from stasis.config.json')
129
- const { addCommand } = await import('../src/add.js')
130
- addCommand({ cwd: process.cwd(), entries: argv, logLabel: 'stasis-core' })
54
+ await addCli(argv, { label: 'stasis-core', fail })
131
55
  } else if (command === 'extract') {
132
- const options = {
133
- output: { type: 'string', short: 'o' },
134
- }
135
- const values = parseLeadingOptions(argv, options, { valueFlags: ['--output', '-o'], onError: usage })
136
- if (argv.length === 0) usage('Nothing to extract: no bundle file given')
137
- if (argv.length > 1) usage('Error: extract takes exactly one bundle file')
138
- const { extractCommand } = await import('../src/extract.js')
139
- extractCommand({ cwd: process.cwd(), bundleFile: argv[0], output: values.output, logLabel: 'stasis-core' })
140
- } else {
56
+ await extractCli(argv, { label: 'stasis-core', fail })
57
+ } else if (command === undefined) {
141
58
  usage()
59
+ } else {
60
+ fail(`Error: unknown command '${command}'`)
142
61
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@exodus/stasis-core",
3
- "version": "1.0.0-beta.8",
3
+ "version": "1.0.0-rc.0",
4
4
  "description": "Zero-dependency stasis runtime",
5
5
  "type": "module",
6
6
  "exports": {
@@ -17,7 +17,9 @@
17
17
  "./util": "./src/util.js",
18
18
  "./brotli": "./src/brotli.js",
19
19
  "./state-util": "./src/state-util.js",
20
- "./prune": "./src/prune.js"
20
+ "./policy": "./src/policy.js",
21
+ "./prune": "./src/prune.js",
22
+ "./cli": "./src/cli.js"
21
23
  },
22
24
  "files": [
23
25
  "bin/stasis-core.js",
@@ -26,6 +28,7 @@
26
28
  "src/brotli.js",
27
29
  "src/bundle.js",
28
30
  "src/bundle-util.js",
31
+ "src/cli.js",
29
32
  "src/config.js",
30
33
  "src/extract.js",
31
34
  "src/fs.js",
@@ -34,6 +37,7 @@
34
37
  "src/loader.js",
35
38
  "src/lockfile.js",
36
39
  "src/package.cjs",
40
+ "src/policy.js",
37
41
  "src/prune.js",
38
42
  "src/shard.js",
39
43
  "src/state.js",