@exodus/stasis-core 1.0.0-beta.7 → 1.0.0-beta.9

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.
@@ -18,21 +18,25 @@ const jsname = argv.shift()
18
18
  const pathsEqual = (a, b) => a === b || (existsSync(a) && realpathSync(a) === b)
19
19
  assert(basename(jsname) === 'stasis-core' || pathsEqual(jsname, fileURLToPath(import.meta.url)))
20
20
 
21
- function usage(prefix = '') {
22
- console.error(`${prefix}\nUsage:
21
+ const HELP = `Usage:
23
22
  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
23
  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
24
  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.)
34
25
  stasis-core prune [path/to/project]
35
- `.trim())
26
+ stasis-core --version
27
+
28
+ Each command's options: https://github.com/PreventiveMeasures/stasis/blob/main/doc/<command>.md
29
+ (run, extract, prune; add is in bundle.md)`
30
+
31
+ // The help, on stderr. Exits 0 when asked for (--help), 1 when printed for want of a command.
32
+ function usage(asked = false) {
33
+ console.error(HELP)
34
+ process.exit(asked ? 0 : 1)
35
+ }
36
+
37
+ // A usage error: the message and where the help is, never the help itself.
38
+ function fail(message) {
39
+ console.error(`${message}\nRun 'stasis-core --help' for usage.`)
36
40
  process.exit(1)
37
41
  }
38
42
 
@@ -47,6 +51,8 @@ const command = argv.shift()
47
51
  if (command === '-v' || command === '--version') {
48
52
  console.log(`v${pkg.version}`)
49
53
  process.exit(0)
54
+ } else if (command === '-h' || command === '--help') {
55
+ usage(true)
50
56
  } else if (command === 'run') {
51
57
  const options = {
52
58
  lock: { type: 'string', default: 'none' },
@@ -63,23 +69,23 @@ if (command === '-v' || command === '--version') {
63
69
  }
64
70
  const values = parseLeadingOptions(argv, options, {
65
71
  valueFlags: ['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--import', '--resources', '--brotli-quality'],
66
- onError: usage,
72
+ onError: fail,
67
73
  })
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')
74
+ if (argv.length === 0) fail('Nothing to run: no path to file given')
75
+ if (!['none', 'ignore', 'add', 'replace', 'frozen'].includes(values.lock)) fail('Error: invalid --lock value')
70
76
  const lock = values.lock
71
77
  const scope = values.dependencies ? 'node_modules' : 'full'
72
78
  const bundle = values.bundle
73
79
  const bundleFile = values['bundle-file'] ? resolve(values['bundle-file']) : ''
74
80
  const resourcesBundleFile = values['resources-bundle-file'] ? resolve(values['resources-bundle-file']) : ''
75
81
  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)')
82
+ if (!['none', 'ignore', 'add', 'replace', 'load', 'frozen'].includes(bundle)) fail('Error: invalid --bundle value')
83
+ if (bundleFile && bundle === 'none') fail('Error: --bundle-file requires --bundle=(add|replace|load|frozen|ignore)')
84
+ if (resourcesBundleFile && (bundle === 'none' || bundle === 'ignore')) fail('Error: --resources-bundle-file requires --bundle=(add|replace|load|frozen)')
85
+ if (bundle === 'load' && lock !== 'frozen' && lock !== 'none' && lock !== 'ignore') fail('Error: --bundle=load is incompatible with --lock=(add|replace)')
86
+ if (lock === 'none' && bundle === 'none') fail('Error: stasis needs a lockfile or a bundle: set --lock or --bundle')
87
+ if (values.fs !== undefined && !['sync', 'async'].includes(values.fs)) fail("Error: --fs must be 'sync' or 'async'")
88
+ if (values.fs !== undefined && !['add', 'replace', 'load'].includes(bundle)) fail('Error: --fs requires --bundle=(add|replace|load)')
83
89
  const captureFs = values.fs ?? ''
84
90
  const resources = values.resources ?? ''
85
91
  let brotliQuality
@@ -87,14 +93,14 @@ if (command === '-v' || command === '--version') {
87
93
  try {
88
94
  brotliQuality = parseBrotliQuality('--brotli-quality', values['brotli-quality'])
89
95
  } catch (cause) {
90
- usage(`Error: ${cause.message}`)
96
+ fail(`Error: ${cause.message}`)
91
97
  }
92
98
  }
93
99
  const childProcess = values['child-process'] ? '1' : ''
94
100
  // --import: extra preload module(s) passed through to the spawned node. Node resolves each
95
101
  // against the project cwd; they ride AFTER stasis's own loader import.
96
102
  const imports = values.import ?? []
97
- if (imports.some((s) => s === '')) usage('Error: --import requires a module specifier (e.g. --import=./instrument.mjs)')
103
+ if (imports.some((s) => s === '')) fail('Error: --import requires a module specifier (e.g. --import=./instrument.mjs)')
98
104
  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
105
  if (debug) console.warn(`[stasis-core] Warning: stasis debug mode active`)
100
106
  setEnv('EXODUS_STASIS_LOCK', lock)
@@ -118,25 +124,27 @@ if (command === '-v' || command === '--version') {
118
124
  // code is null when the child died from a signal; report 128+signo (shell convention) instead of the implicit 0
119
125
  process.exitCode = code ?? 128 + (osConstants.signals[signal] ?? 0)
120
126
  } else if (command === 'prune') {
121
- if (argv.length > 1) usage('Error: prune takes at most one path argument')
127
+ if (argv.length > 1) fail('Error: prune takes at most one path argument')
122
128
  const root = argv[0] ? resolve(argv[0]) : process.cwd()
123
129
  const { prune } = await import('../src/prune.js')
124
130
  const { removed, validated, minimized } = prune({ root })
125
131
  console.warn(`[stasis-core] prune: validated ${validated.length} file(s), removed ${removed.length} file(s), minimized ${minimized.length} package.json file(s)`)
126
132
  } 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')
133
+ if (argv.length === 0) fail('Nothing to add: no file given')
134
+ if (argv.some((a) => a.startsWith('-'))) fail('Error: add takes no options; its targets and resource allowlist come from stasis.config.json')
129
135
  const { addCommand } = await import('../src/add.js')
130
136
  addCommand({ cwd: process.cwd(), entries: argv, logLabel: 'stasis-core' })
131
137
  } else if (command === 'extract') {
132
138
  const options = {
133
139
  output: { type: 'string', short: 'o' },
134
140
  }
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')
141
+ const values = parseLeadingOptions(argv, options, { valueFlags: ['--output', '-o'], onError: fail })
142
+ if (argv.length === 0) fail('Nothing to extract: no bundle file given')
143
+ if (argv.length > 1) fail('Error: extract takes exactly one bundle file')
138
144
  const { extractCommand } = await import('../src/extract.js')
139
145
  extractCommand({ cwd: process.cwd(), bundleFile: argv[0], output: values.output, logLabel: 'stasis-core' })
140
- } else {
146
+ } else if (command === undefined) {
141
147
  usage()
148
+ } else {
149
+ fail(`Error: unknown command '${command}'`)
142
150
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@exodus/stasis-core",
3
- "version": "1.0.0-beta.7",
3
+ "version": "1.0.0-beta.9",
4
4
  "description": "Zero-dependency stasis runtime",
5
5
  "type": "module",
6
6
  "exports": {
@@ -25,6 +25,10 @@ export const KNOWN_FORMATS = new Set([
25
25
  // Payload-free stat records: attest a path's KIND, no content, and yield to a real format.
26
26
  export const isStatFormat = (format) => STAT_FORMATS.has(format)
27
27
 
28
+ // Reserved synthetic file a disabled import (a `browser`/`react-native` field mapping it to `false`)
29
+ // points at: never on disk, carried as empty CommonJS so the edge resolves to attested bytes.
30
+ export const EMPTY_MODULE_PATH = '.stasis/empty-module.js'
31
+
28
32
  // The post-erasure family of a '-typescript' loader format ('module-typescript' -> 'module'): a
29
33
  // transforming preload (`stasis run --import tsx`) resolves/serves a TypeScript file as the JS
30
34
  // family it transpiles to, while the attestation keeps the on-disk format. undefined otherwise.
@@ -95,12 +99,15 @@ export const normalizeRepo = (repo, what = 'bundle repo') => normalizeBlock(repo
95
99
  // node_modules (an artifact from before the tag); undefined for first-party code.
96
100
  export const dependencyEcosystem = (dir, ecosystem) => ecosystem ?? (hasNodeModulesSegment(dir) ? 'npm' : undefined)
97
101
 
98
- // A dependency's `repo`, the one its own manifest names, with the bundle's own fields; first-party
102
+ // A dependency's `repo`, the one its own manifest names, with the bundle's own fields, `github`
103
+ // required: a `directory` or `commit` places nothing without the repository it is in. First-party
99
104
  // code carries none.
100
105
  const normalizeModuleRepo = (dir, { ecosystem, repo }, what) => {
101
106
  if (repo === undefined) return undefined
102
107
  if (dependencyEcosystem(dir, ecosystem) === undefined) assert(false, `${what}: '${dir}' is no dependency's bucket, and carries no repo`)
103
- return normalizeRepo(repo, `${what} module '${dir}' repo`)
108
+ const normalized = normalizeRepo(repo, `${what} module '${dir}' repo`)
109
+ if (normalized?.github === undefined) assert(false, `${what} module '${dir}' repo has no github`)
110
+ return normalized
104
111
  }
105
112
 
106
113
  // A module bucket record in canonical key order; `ecosystem` and `repo` are omitted (not undefined) when absent.
@@ -159,10 +159,10 @@ export function readJson(file, host = diskHost) {
159
159
  // npm lets it name is no part of the repo; a URL's userinfo holds only what RFC 3986 allows there, so
160
160
  // a `?` or `\` ending the authority early (`https://evil.example?@github.com/a/b`) isn't GitHub's. An
161
161
  // scp-like `git@github.com:owner/name` is taken behind an `ssh://` too (`git+ssh://git@github.com:o/n`),
162
- // as package.json files spell it.
162
+ // as package.json files spell it. The host is GitHub's with a `www.` too, which is stripped.
163
163
  export function parseGithubRepository(url) {
164
164
  if (typeof url !== 'string') return null
165
- const match = /^(?:github:|(?:git\+)?(?:(?:https?|ssh|git):\/\/(?:[\w.~%!$&'()*+,;=:-]*@)?github\.com(?::\d+)?\/|ssh:\/\/(?:[\w.~%!$&'()*+,;=-]*@)?github\.com:|(?:[^@/:]+@)?github\.com:))?([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/iu.exec(url.trim().replace(/#.*$/su, ''))
165
+ const match = /^(?:github:|(?:git\+)?(?:(?:https?|ssh|git):\/\/(?:[\w.~%!$&'()*+,;=:-]*@)?(?:www\.)?github\.com(?::\d+)?\/|ssh:\/\/(?:[\w.~%!$&'()*+,;=-]*@)?(?:www\.)?github\.com:|(?:[^@/:]+@)?(?:www\.)?github\.com:))?([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/iu.exec(url.trim().replace(/#.*$/su, ''))
166
166
  // Must also pass the bundle format's `github` check.
167
167
  const github = match && `${match[1]}/${match[2]}`
168
168
  return github && isValidRepoField('github', github) ? github : null
@@ -240,6 +240,14 @@ function gitHeadCommit({ gitDir, commonDir }, host) {
240
240
  return isValidRepoField('commit', commit) ? commit : undefined
241
241
  }
242
242
 
243
+ // HEAD's commit of the git checkout at `dir` (gitHeadCommit), its `.git` a directory or the `gitdir:`
244
+ // file of a submodule or worktree; undefined where it holds none. Read through `host`, under `.git`
245
+ // alone; git never runs.
246
+ export function checkoutCommit(dir, host = diskHost) {
247
+ const dotGit = join(dir, '.git')
248
+ return host.stat(dotGit) === null ? undefined : gitHeadCommit(gitDirs(dotGit, host), host)
249
+ }
250
+
243
251
  // A parsed package.json's `repository` url (the string shorthand, or its `url`), or undefined.
244
252
  function repositoryUrl(json) {
245
253
  const repository = json?.repository
package/src/state.js CHANGED
@@ -11,7 +11,7 @@ import { Lockfile } from './lockfile.js'
11
11
  import { parseShard, serializeShard } from './shard.js'
12
12
  import { canonicalizePath, sha512integrity, readFileSyncMaybe, noupsert } from './state-util.js'
13
13
  import { brotliOptions } from './brotli.js'
14
- import { CODE_EXTENSIONS, canObserveExecuteBits, classifyFormat, erasedTypeScriptFormat, fileMapToObject, hasNodeModulesSegment, isBinaryPlist, isNativeArtifact, isPathWithin, isStatFormat, moduleFileKey, moduleInfo, narrowExecutable, nestedMap, objectToMaps, observeExecutable, pathExt, reconcileFormat, relativeEscapes, sortPaths, splitNodeModulesPath } from './util.js'
14
+ import { CODE_EXTENSIONS, EMPTY_MODULE_PATH, canObserveExecuteBits, classifyFormat, erasedTypeScriptFormat, fileMapToObject, hasNodeModulesSegment, isBinaryPlist, isNativeArtifact, isPathWithin, isStatFormat, moduleFileKey, moduleInfo, narrowExecutable, nestedMap, objectToMaps, observeExecutable, pathExt, reconcileFormat, relativeEscapes, sortPaths, splitNodeModulesPath } from './util.js'
15
15
  import { detectRepo, packageJSONStat, packageJSONText, packageRepo, readModuleManifest } from './bundle-util.js'
16
16
  import { diskHost } from './host.js'
17
17
  import corePackage from './package.cjs'
@@ -723,13 +723,19 @@ export class State {
723
723
 
724
724
  // Canonicalize `url` and resolve/register the owning package bucket. `directory: true` walks up
725
725
  // ourselves -- Node's findPackageJSON is unreliable for a directory URL (EISDIR, or the parent's).
726
- #locateModule(url, { directory = false } = {}) {
726
+ // `synthetic: true` (EMPTY_MODULE_PATH) is never on disk: it must NOT exist, and walks up from its dir.
727
+ #locateModule(url, { directory = false, synthetic = false } = {}) {
727
728
  // Canonicalize first: a linked-in workspace source is recorded under its real path (a source).
728
729
  const { absolute } = this.#canonical(url)
729
- assert.ok(this.#host.stat(absolute) !== null)
730
730
  const file = this.relative(absolute)
731
+ if (synthetic) {
732
+ assert.ok(this.#host.stat(absolute) === null, `the reserved path ${file} is needed for a synthetic empty module, but the project has a real file there`)
733
+ } else {
734
+ assert.ok(this.#host.stat(absolute) !== null)
735
+ }
731
736
 
732
- const closestPkgAbsolute = directory ? this.#nearestPackageJsonFor(absolute) : this.#host.findPackageJSON(absolute)
737
+ const closestPkgAbsolute = directory ? this.#nearestPackageJsonFor(absolute)
738
+ : synthetic ? this.#nearestPackageJsonFor(dirname(absolute)) : this.#host.findPackageJSON(absolute)
733
739
  const closestPkg = readPackageJSON(this.#host, closestPkgAbsolute)
734
740
 
735
741
  const closestType = closestPkg.type
@@ -794,7 +800,19 @@ export class State {
794
800
 
795
801
  // `resource: true` (legacy alias `isBinary: true`): format derived from bytes. `inferFormat: false`
796
802
  // records bytes without imposing a loader format (defers module-vs-commonjs to the loader).
797
- addFile(url, { source, format, isEntry, isBinary, resource, inferFormat = true, reason = 'run', fsRead = false } = {}) {
803
+ addFile(url, options = {}) {
804
+ this.#addFile(url, options)
805
+ }
806
+
807
+ // Record the empty module a disabled import resolves to (EMPTY_MODULE_PATH, the file `stasis bundle`
808
+ // emits for a `browser` field `false`), attested like any file but never read from disk. -> its URL
809
+ addEmptyModule({ reason = 'run' } = {}) {
810
+ const url = pathToFileURL(resolve(this.root, EMPTY_MODULE_PATH)).toString()
811
+ this.#addFile(url, { source: '', format: 'commonjs', inferFormat: false, reason }, { synthetic: true })
812
+ return url
813
+ }
814
+
815
+ #addFile(url, { source, format, isEntry, isBinary, resource, inferFormat = true, reason = 'run', fsRead = false } = {}, { synthetic = false } = {}) {
798
816
  const asResource = resource === true || isBinary === true
799
817
  if (!asResource && Bundle.isResourceFormat(format)) {
800
818
  throw new Error(`addFile: format '${format}' requires resource: true`)
@@ -805,7 +823,7 @@ export class State {
805
823
  if (asResource && isEntry) {
806
824
  throw new Error(`addFile: a resource can't be an entry (resource:true + isEntry:true)`)
807
825
  }
808
- const { absolute, file, dir, module, closestType } = this.#locateModule(url)
826
+ const { absolute, file, dir, module, closestType } = this.#locateModule(url, { synthetic })
809
827
 
810
828
  // Real content supersedes a payload-free stat record: drop it so the noupsert below records the
811
829
  // actual format instead of conflicting with 'stat:*'.
@@ -855,7 +873,7 @@ export class State {
855
873
 
856
874
  const buf = typeof source === 'string' ? Buffer.from(source) : source
857
875
  // Verify a CALLER-PROVIDED source against disk; tautological when we read it ourselves.
858
- if (!sourceFromDisk) assert.deepStrictEqual(this.#host.readFile(absolute), buf)
876
+ if (!sourceFromDisk && !synthetic) assert.deepStrictEqual(this.#host.readFile(absolute), buf)
859
877
 
860
878
  if (asResource) {
861
879
  const derived = isUtf8(buf) ? 'resource' : 'resource:base64'
@@ -920,7 +938,7 @@ export class State {
920
938
 
921
939
  if (format) noupsert(this.formats, file, format)
922
940
 
923
- this.#recordExecutable(file, absolute)
941
+ if (!synthetic) this.#recordExecutable(file, absolute)
924
942
  }
925
943
 
926
944
  // Observe `file` on disk and record or refute its execute bit; disk wins over whatever a lockfile/