@exodus/stasis-core 1.0.0-beta.1 → 1.0.0-beta.11

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/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # <img src="/stasis/logo.svg" alt="" width="39" height="39" valign="bottom" /> `@exodus/stasis-core`
2
2
 
3
- A minimal subset of `@exodus/stasis` with just `run` and `prune` commands.
3
+ A minimal subset of `@exodus/stasis` with just the `run`, `add`, `extract`, and `prune` commands.
4
4
 
5
5
  See main package [GitHub](https://github.com/ExodusOSS/stasis/tree/main/stasis) or [npm](https://npmjs.com/package/@exodus/stasis) for full README.
6
6
 
@@ -1,13 +1,13 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  import { spawn } from 'node:child_process'
4
- import { parseArgs } from 'node:util'
5
4
  import { once } from 'node:events'
6
5
  import { fileURLToPath } from 'node:url'
7
6
  import { basename, resolve } from 'node:path'
8
7
  import { existsSync, realpathSync } from 'node:fs'
9
8
  import { constants as osConstants } from 'node:os'
10
9
  import assert from 'node:assert/strict'
10
+ import { parseBrotliQuality, parseLeadingOptions } from '../src/util.js'
11
11
  import pkg from '../package.json' with { type: 'json' }
12
12
 
13
13
  const argv = [...process.argv]
@@ -15,14 +15,28 @@ assert(['node', 'node.exe'].includes(basename(argv.shift())))
15
15
  assert(['node', 'node.exe'].includes(basename(process.argv0)))
16
16
 
17
17
  const jsname = argv.shift()
18
- const pathsEqual = (a, b) => a === b || (existsSync(a) && realpathSync(a) === b) // resolve symlinks
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:
23
- 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] [--fs=(sync|async)] [--resources=ext,ext] path/to/file.js ...
21
+ const HELP = `Usage:
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 ...
23
+ stasis-core add path/to/(file|dir) ...
24
+ stasis-core extract [--output=path/to/dir] path/to/bundle.stasis.code.br
24
25
  stasis-core prune [path/to/project]
25
- `.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.`)
26
40
  process.exit(1)
27
41
  }
28
42
 
@@ -37,13 +51,9 @@ const command = argv.shift()
37
51
  if (command === '-v' || command === '--version') {
38
52
  console.log(`v${pkg.version}`)
39
53
  process.exit(0)
54
+ } else if (command === '-h' || command === '--help') {
55
+ usage(true)
40
56
  } else if (command === 'run') {
41
- const flags = []
42
- const valueFlags = new Set(['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--resources'])
43
- while (argv.length > 0 && (argv[0].startsWith('-') || valueFlags.has(flags.at(-1)))) {
44
- flags.push(argv.shift())
45
- }
46
-
47
57
  const options = {
48
58
  lock: { type: 'string', default: 'none' },
49
59
  bundle: { type: 'string', default: 'none' },
@@ -52,46 +62,46 @@ if (command === '-v' || command === '--version') {
52
62
  debug: { type: 'boolean' },
53
63
  dependencies: { type: 'boolean' },
54
64
  'child-process': { type: 'boolean' },
65
+ import: { type: 'string', multiple: true },
55
66
  fs: { type: 'string' },
56
67
  resources: { type: 'string' },
68
+ 'brotli-quality': { type: 'string' },
57
69
  }
58
-
59
- let values
60
- try {
61
- ({ values } = parseArgs({ args: flags, options }))
62
- } catch (cause) {
63
- usage(`Error: ${cause.message}`)
64
- }
65
- if (argv.length === 0) usage('Nothing to run: no path to file given')
66
- if (!['none', 'ignore', 'add', 'replace', 'frozen'].includes(values.lock)) usage('Error: invalid --lock value')
70
+ const values = parseLeadingOptions(argv, options, {
71
+ valueFlags: ['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--import', '--resources', '--brotli-quality'],
72
+ onError: fail,
73
+ })
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')
67
76
  const lock = values.lock
68
77
  const scope = values.dependencies ? 'node_modules' : 'full'
69
78
  const bundle = values.bundle
70
79
  const bundleFile = values['bundle-file'] ? resolve(values['bundle-file']) : ''
71
80
  const resourcesBundleFile = values['resources-bundle-file'] ? resolve(values['resources-bundle-file']) : ''
72
81
  const debug = values.debug ? '1' : ''
73
- if (!['none', 'ignore', 'add', 'replace', 'load', 'frozen'].includes(bundle)) usage('Error: invalid --bundle value')
74
- if (bundleFile && bundle === 'none') usage('Error: --bundle-file requires --bundle=(add|replace|load|frozen|ignore)')
75
- // Unlike --bundle-file (which is inert-but-harmless under --bundle=ignore, so Config allows
76
- // it), --resources-bundle-file needs an active bundle: Config rejects bundle=none AND ignore
77
- // (resourcesBundleFile requires an active bundle mode). Front-run that with a clean usage error.
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
- // --fs monkey-patches the fs readers (readFileSync/readdirSync + lstatSync/statSync)
82
- // to capture them into the bundle (add|replace) or serve them from it (load); nothing
83
- // to record/read without one. The mode argument is required: `sync` patches the sync
84
- // readers, `async` adds their async (callback + fs.promises) counterparts on top.
85
- if (values.fs !== undefined && !['sync', 'async'].includes(values.fs)) usage("Error: --fs must be 'sync' or 'async'")
86
- 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)')
87
89
  const captureFs = values.fs ?? ''
88
- // --resources: comma-separated extension/filename allowlist for `--fs` resource captures
89
- // (e.g. png,svg,LICENSE). The child's Config validates each entry via parseResourcesOption.
90
90
  const resources = values.resources ?? ''
91
- // --child-process: forward forked-child (e.g. Metro transform worker) capture to the root
92
- // via per-pid shards. Opt-in -- it stands up a process-coordination channel, off by default.
91
+ let brotliQuality
92
+ if (values['brotli-quality'] !== undefined) {
93
+ try {
94
+ brotliQuality = parseBrotliQuality('--brotli-quality', values['brotli-quality'])
95
+ } catch (cause) {
96
+ fail(`Error: ${cause.message}`)
97
+ }
98
+ }
93
99
  const childProcess = values['child-process'] ? '1' : ''
94
- console.warn('[stasis-core] Running stasis with config:', { lock, scope, bundle, ...(bundleFile && { bundleFile }), ...(resourcesBundleFile && { resourcesBundleFile }), ...(childProcess && { childProcess: true }), ...(values.fs && { fs: values.fs }), ...(resources && { resources }) })
100
+ // --import: extra preload module(s) passed through to the spawned node. Node resolves each
101
+ // against the project cwd; they ride AFTER stasis's own loader import.
102
+ const imports = values.import ?? []
103
+ if (imports.some((s) => s === '')) fail('Error: --import requires a module specifier (e.g. --import=./instrument.mjs)')
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 }) })
95
105
  if (debug) console.warn(`[stasis-core] Warning: stasis debug mode active`)
96
106
  setEnv('EXODUS_STASIS_LOCK', lock)
97
107
  setEnv('EXODUS_STASIS_SCOPE', scope)
@@ -102,17 +112,39 @@ if (command === '-v' || command === '--version') {
102
112
  setEnv('EXODUS_STASIS_CHILD_PROCESS', childProcess)
103
113
  setEnv('EXODUS_STASIS_FS', captureFs)
104
114
  setEnv('EXODUS_STASIS_RESOURCES', resources)
115
+ // Only set when given: an unconditional setEnv('') would reject an ambient EXODUS_STASIS_BROTLI_QUALITY as a conflict.
116
+ if (brotliQuality !== undefined) setEnv('EXODUS_STASIS_BROTLI_QUALITY', String(brotliQuality))
105
117
  const nodeArgs = ['--import', import.meta.resolve('../src/loader.js')]
118
+ // Passthrough preloads ride after the loader, so they evaluate under its hooks; their module
119
+ // graphs pass through uncaptured unless the app graph reaches them -- then they're promoted
120
+ // into the capture (see src/hooks.js).
121
+ for (const specifier of imports) nodeArgs.push('--import', specifier)
106
122
  const child = spawn(process.execPath, [...nodeArgs, ...argv], { stdio: 'inherit' })
107
123
  const [code, signal] = await once(child, 'close')
108
124
  // code is null when the child died from a signal; report 128+signo (shell convention) instead of the implicit 0
109
125
  process.exitCode = code ?? 128 + (osConstants.signals[signal] ?? 0)
110
126
  } else if (command === 'prune') {
111
- 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')
112
128
  const root = argv[0] ? resolve(argv[0]) : process.cwd()
113
129
  const { prune } = await import('../src/prune.js')
114
130
  const { removed, validated, minimized } = prune({ root })
115
131
  console.warn(`[stasis-core] prune: validated ${validated.length} file(s), removed ${removed.length} file(s), minimized ${minimized.length} package.json file(s)`)
116
- } else {
132
+ } else if (command === 'add') {
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')
135
+ const { addCommand } = await import('../src/add.js')
136
+ addCommand({ cwd: process.cwd(), entries: argv, logLabel: 'stasis-core' })
137
+ } else if (command === 'extract') {
138
+ const options = {
139
+ output: { type: 'string', short: 'o' },
140
+ }
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')
144
+ const { extractCommand } = await import('../src/extract.js')
145
+ extractCommand({ cwd: process.cwd(), bundleFile: argv[0], output: values.output, logLabel: 'stasis-core' })
146
+ } else if (command === undefined) {
117
147
  usage()
148
+ } else {
149
+ fail(`Error: unknown command '${command}'`)
118
150
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@exodus/stasis-core",
3
- "version": "1.0.0-beta.1",
3
+ "version": "1.0.0-beta.11",
4
4
  "description": "Zero-dependency stasis runtime",
5
5
  "type": "module",
6
6
  "exports": {
@@ -9,6 +9,10 @@
9
9
  "./state": "./src/state.js",
10
10
  "./config": "./src/config.js",
11
11
  "./bundle": "./src/bundle.js",
12
+ "./add": "./src/add.js",
13
+ "./bundle-util": "./src/bundle-util.js",
14
+ "./extract": "./src/extract.js",
15
+ "./host": "./src/host.js",
12
16
  "./lockfile": "./src/lockfile.js",
13
17
  "./util": "./src/util.js",
14
18
  "./brotli": "./src/brotli.js",
@@ -17,15 +21,21 @@
17
21
  },
18
22
  "files": [
19
23
  "bin/stasis-core.js",
24
+ "src/add.js",
25
+ "src/artifact-util.js",
20
26
  "src/brotli.js",
21
27
  "src/bundle.js",
28
+ "src/bundle-util.js",
22
29
  "src/config.js",
30
+ "src/extract.js",
23
31
  "src/fs.js",
24
32
  "src/hooks.js",
33
+ "src/host.js",
25
34
  "src/loader.js",
26
35
  "src/lockfile.js",
27
36
  "src/package.cjs",
28
37
  "src/prune.js",
38
+ "src/shard.js",
29
39
  "src/state.js",
30
40
  "src/state-util.js",
31
41
  "src/util.js"
@@ -38,13 +48,13 @@
38
48
  },
39
49
  "repository": {
40
50
  "type": "git",
41
- "url": "git+https://github.com/ExodusOSS/stasis.git",
51
+ "url": "git+https://github.com/PreventiveMeasures/stasis.git",
42
52
  "directory": "stasis-core"
43
53
  },
44
54
  "author": "Exodus Movement, Inc.",
45
55
  "license": "MIT",
46
56
  "bugs": {
47
- "url": "https://github.com/ExodusOSS/stasis/issues"
57
+ "url": "https://github.com/PreventiveMeasures/stasis/issues"
48
58
  },
49
- "homepage": "https://github.com/ExodusOSS/stasis#readme"
59
+ "homepage": "https://github.com/PreventiveMeasures/stasis#readme"
50
60
  }
package/src/add.js ADDED
@@ -0,0 +1,317 @@
1
+ import { isUtf8 } from 'node:buffer'
2
+ import { existsSync, globSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
3
+ import { basename, dirname, extname, join, relative, resolve } from 'node:path'
4
+ import { brotliCompressSync, brotliDecompressSync } from 'node:zlib'
5
+
6
+ import { Bundle } from './bundle.js'
7
+ import { Lockfile } from './lockfile.js'
8
+ import { brotliOptions } from './brotli.js'
9
+ import { detectRepo, findPackageMetadata, normalizeEntries, packageType, readJson } from './bundle-util.js'
10
+ import { canonicalizePath, sha512integrity } from './state-util.js'
11
+ import { assertRealPathWithinBase, classifyFormat, hasNodeModulesSegment, isAutoExcludedDir, isAutoExcludedFile, isBinaryPlist, isBrotliQuality, isExecutableMode, moduleFileKey, moduleInfo, parseResourcesOption, pathExt, sortPaths, splitNodeModulesPath, toPosix, withMetadataOf } from './util.js'
12
+
13
+ const CONFIG_FILE = 'stasis.config.json'
14
+ const LOCK_FILE = 'stasis.lock.json'
15
+
16
+ // A `.js`/`.ts` follows its package `type` (LIMITATION: none falls back to commonjs -- use `.mjs`/`.cjs`
17
+ // or set `type` when the module system matters). Any other name is classifyFormat's call: a format,
18
+ // null for a JS-family file (`.jsx`/`.tsx`: source attested with no loader format, as the runtime
19
+ // records one), undefined when unrecognized.
20
+ function sourceFormat(absFile, content) {
21
+ const ext = extname(absFile).toLowerCase()
22
+ if (ext === '.js' || ext === '.ts') return `${packageType(absFile) ?? 'commonjs'}${ext === '.ts' ? '-typescript' : ''}`
23
+ return classifyFormat(absFile, { content })
24
+ }
25
+
26
+ // File and non-empty package counts of a bundle or lockfile.
27
+ const tally = (artifact) => {
28
+ let files = 0
29
+ let packages = 0
30
+ for (const m of artifact.modules.values()) {
31
+ const n = Object.keys(m.files).length
32
+ if (n > 0) {
33
+ files += n
34
+ packages += 1
35
+ }
36
+ }
37
+ return { files, packages }
38
+ }
39
+
40
+ function readAddConfig(baseDir) {
41
+ const cfg = readJson(join(baseDir, CONFIG_FILE))
42
+ if (cfg === null) {
43
+ throw new Error(`add requires a ${CONFIG_FILE} (its bundleFile, resourcesBundleFile, and resources are all optional)`)
44
+ }
45
+ const resources = parseResourcesOption(CONFIG_FILE, cfg.resources)
46
+ if (cfg.brotliQuality !== undefined && !isBrotliQuality(cfg.brotliQuality)) {
47
+ throw new Error(`${CONFIG_FILE}: brotliQuality must be an integer 0..11 (got ${JSON.stringify(cfg.brotliQuality)})`)
48
+ }
49
+ const bundleFile = cfg.bundleFile ?? 'stasis.code.br'
50
+ const resourcesBundleFile = cfg.resourcesBundleFile
51
+ // Split targets must be distinct files (else they clobber on write); canonicalized so symlink and relative aliases are caught too.
52
+ if (resourcesBundleFile &&
53
+ canonicalizePath(resolve(baseDir, bundleFile)) === canonicalizePath(resolve(baseDir, resourcesBundleFile))) {
54
+ throw new Error(`${CONFIG_FILE}: bundleFile and resourcesBundleFile must name distinct paths (both resolve to ${resolve(baseDir, bundleFile)})`)
55
+ }
56
+ return { bundleFile, resourcesBundleFile, resources, brotliQuality: cfg.brotliQuality }
57
+ }
58
+
59
+ // Assemble a Bundle bucketed per package.json. `add` records NO entries -- its files are attested, not entry points -- so nothing in an add bundle is runnable via `--bundle=load`.
60
+ function assembleBundle(baseDir, files, workspaceName, workspaceVersion, repo) {
61
+ const modules = new Map()
62
+ const formats = new Map()
63
+ const executable = new Set()
64
+ // `identity`'s name, version, ecosystem, repo and vendored (moduleInfo takes those alone); a later
65
+ // file's adds the vendored package it is in.
66
+ const bucketFiles = (dir, identity) => {
67
+ const bucket = modules.get(dir)
68
+ modules.set(dir, bucket === undefined ? moduleInfo({ ...identity, files: Object.create(null) }) : withMetadataOf(bucket, identity))
69
+ return modules.get(dir).files
70
+ }
71
+ // findPackageMetadata's result depends only on the file's directory.
72
+ const metaByDir = new Map()
73
+ const metaFor = (rel) => {
74
+ const dir = dirname(rel)
75
+ if (!metaByDir.has(dir)) metaByDir.set(dir, findPackageMetadata(baseDir, rel))
76
+ return metaByDir.get(dir)
77
+ }
78
+
79
+ for (const [rel, { content, format, executable: isExec }] of files) {
80
+ const meta = metaFor(rel)
81
+ // A node_modules file whose nearest package.json is the workspace root (or none at all) is a misconfigured dep -- refuse.
82
+ if (splitNodeModulesPath(rel) !== null && !(meta && hasNodeModulesSegment(meta.pkgDir))) {
83
+ throw new Error(`add: no package.json with name+version found for ${rel}`)
84
+ }
85
+ if (meta) {
86
+ const relInBucket = meta.pkgDir === '.' ? rel : rel.slice(meta.pkgDir.length + 1)
87
+ bucketFiles(meta.pkgDir, meta)[relInBucket] = content
88
+ } else {
89
+ bucketFiles('.', { name: workspaceName, version: workspaceVersion })[rel] = content
90
+ }
91
+ if (format != null) formats.set(rel, format)
92
+ if (isExec) executable.add(rel)
93
+ }
94
+
95
+ return new Bundle({ config: { scope: 'full' }, entries: new Set(), modules, formats, imports: new Map(), executable, repo }).withReason('add')
96
+ }
97
+
98
+ // Merge add-if-missing into any existing bundle (divergent bytes for an attested path throw -- see
99
+ // mergeModuleMaps), returning the write as a thunk so every target's conflicts surface before the
100
+ // first byte lands and an aborted `add` leaves the project untouched. Serializing INSIDE the thunk
101
+ // keeps peak memory at one target's bytes rather than every target's at once.
102
+ function prepareBundleFile(baseDir, targetPath, bundle, brotliQuality) {
103
+ const abs = resolve(baseDir, targetPath)
104
+ let mergedFrom
105
+ if (existsSync(abs)) {
106
+ let existing
107
+ try {
108
+ existing = Bundle.parse(brotliDecompressSync(readFileSync(abs)).toString('utf8'))
109
+ } catch (cause) {
110
+ throw new Error(`add: failed to read the existing bundle at ${targetPath}`, { cause })
111
+ }
112
+ mergedFrom = tally(existing).files
113
+ bundle = existing.merge(bundle)
114
+ }
115
+ const { files, packages } = tally(bundle)
116
+ return {
117
+ write: () => {
118
+ mkdirSync(dirname(abs), { recursive: true })
119
+ writeFileSync(abs, brotliCompressSync(bundle.serialize(), brotliOptions(brotliQuality)))
120
+ },
121
+ counts: { path: targetPath, total: files, packages, added: mergedFrom === undefined ? files : files - mergedFrom },
122
+ }
123
+ }
124
+
125
+ // Companion Lockfile: the bundle's shape with each file's content swapped for its on-disk integrity, so `--lock=frozen` matches.
126
+ function bundleToLockfile(bundle, integrities) {
127
+ const modules = new Map()
128
+ for (const [dir, m] of bundle.modules) {
129
+ const files = Object.create(null)
130
+ for (const rel of Object.keys(m.files)) files[rel] = integrities.get(moduleFileKey(dir, rel))
131
+ modules.set(dir, moduleInfo({ ...m, files }))
132
+ }
133
+ return new Lockfile({ config: bundle.config, entries: bundle.entries, modules, imports: bundle.imports, formats: bundle.formats, executable: bundle.executable })
134
+ }
135
+
136
+ // Merge into the project's stasis.lock.json (strict: divergent bytes throw), deferring the write like
137
+ // prepareBundleFile so a conflict here doesn't leave the bundles updated.
138
+ function prepareLockfile(lockPath, lockAdd) {
139
+ let existing
140
+ try {
141
+ existing = Lockfile.parse(readFileSync(lockPath, 'utf8'))
142
+ } catch (cause) {
143
+ throw new Error(`add: failed to read the existing ${LOCK_FILE}`, { cause })
144
+ }
145
+ const before = tally(existing).files
146
+ const merged = existing.merge(lockAdd)
147
+ const total = tally(merged).files
148
+ return { write: () => writeFileSync(lockPath, merged.serialize()), counts: { total, added: total - before } }
149
+ }
150
+
151
+ // GLOB + FILTER: expand each directory entry into the files under it (recursive glob), dropping the
152
+ // auto-excluded set from what a sweep FINDS -- dir rules on the segments BELOW the named root (`add
153
+ // src/examples` sweeps the dir it was pointed at, `add src` skips one it merely found), file rules
154
+ // by name plus the caller's `outputs` (this run's own write targets). A path the caller NAMED is
155
+ // always kept (naming is the override; a missing one keeps stats undefined so validation reports
156
+ // it), and inclusion is monotone: a nearer root's sweep can only ever see FEWER excluded segments,
157
+ // so a path any entry keeps stays kept -- `add src src/examples` includes the subtree it names in
158
+ // either order. `stats` is the walk's own stat, reused by validation. Gotcha: `**/*` skips dotfiles
159
+ // (.env, .git/...) -- name them explicitly.
160
+ function expandDirectories(baseDir, rels, outputs) {
161
+ const files = new Map() // rel -> stats
162
+ const excluded = new Set()
163
+ for (const rel of rels) {
164
+ const dirAbs = join(baseDir, rel)
165
+ const stats = statSync(dirAbs, { throwIfNoEntry: false })
166
+ if (stats === undefined || !stats.isDirectory()) {
167
+ files.set(rel, stats)
168
+ continue
169
+ }
170
+ const found = []
171
+ for (const match of globSync('**/*', { cwd: dirAbs })) {
172
+ const fileAbs = join(dirAbs, match)
173
+ // A dangling symlink stats as undefined -- skipped, not a hard ENOENT out of the walk.
174
+ const fileStats = statSync(fileAbs, { throwIfNoEntry: false })
175
+ if (fileStats?.isFile()) found.push([toPosix(relative(baseDir, fileAbs)), match, fileStats])
176
+ }
177
+ // Sorted so the sweep is deterministic regardless of readdir order: artifact bytes are
178
+ // canonicalized by serialize() either way, but multi-file diagnostics keep a stable order.
179
+ for (const [file, match, fileStats] of found.toSorted(([a], [b]) => sortPaths(a, b))) {
180
+ if (toPosix(match).split('/').slice(0, -1).some(isAutoExcludedDir)
181
+ || outputs.has(file) || isAutoExcludedFile(file)) excluded.add(file)
182
+ else files.set(file, fileStats)
183
+ }
184
+ }
185
+ // A path any entry kept can't count as skipped -- another root's sweep may have re-flagged it.
186
+ for (const file of files.keys()) excluded.delete(file)
187
+ return { files, excluded }
188
+ }
189
+
190
+ const listPaths = (rels) => [...rels].toSorted(sortPaths).join(', ')
191
+
192
+ // One error for every file validation rejected, so a directory sweep names all of them at once
193
+ // instead of one per re-run. A lone offender keeps its exact standalone message.
194
+ function validationError({ missing, undeclared, nonUtf8 }) {
195
+ const phrase = (items, one, many) => (items.length === 1 ? [one(items[0])] : items.length > 1 ? [many(items)] : [])
196
+ const withFormat = (format) => (format == null ? '' : ` (format '${format}')`)
197
+ const named = ({ rel, format }) => `${rel}${withFormat(format)}`
198
+ const parts = [
199
+ ...phrase(missing,
200
+ (rel) => `file not found: ${rel}`,
201
+ (rels) => `${rels.length} files not found: ${listPaths(rels)}`),
202
+ ...phrase(undeclared,
203
+ (rel) => `${rel} is neither a recognized source file nor a declared resource; add its extension to "resources" in ${CONFIG_FILE}`,
204
+ (rels) => `${rels.length} files are neither recognized source files nor declared resources; add their extensions to "resources" in ${CONFIG_FILE}: ${listPaths(rels)}`),
205
+ ...phrase(nonUtf8,
206
+ ({ rel, format }) => `${rel} is not valid UTF-8${withFormat(format)}`,
207
+ (bad) => `${bad.length} files are not valid UTF-8: ${bad.map(named).join(', ')}`),
208
+ ]
209
+ return new Error(`add: ${parts.join('; ')}`)
210
+ }
211
+
212
+ // VALIDATE step: classify the WHOLE set -- each file recognized source or a declared resource --
213
+ // before a single target is touched, collecting every offender into one error. `files` is the glob
214
+ // step's rel -> stats map (stats undefined = not on disk). Containment is the one rule NOT collected:
215
+ // a symlink escaping the root is a security invariant, so it fails closed on the spot. Bytes are
216
+ // hashed only when there's a lockfile to receive the integrities (`withIntegrity`).
217
+ function validateFiles({ baseDir, realBase, files, resources, withIntegrity }) {
218
+ const codeFiles = new Map()
219
+ const resourceFiles = new Map()
220
+ const integrities = new Map()
221
+ const missing = []
222
+ const undeclared = []
223
+ const nonUtf8 = []
224
+ for (const [rel, stats] of files) {
225
+ if (stats === undefined) {
226
+ missing.push(rel)
227
+ continue
228
+ }
229
+ const executable = isExecutableMode(stats)
230
+ assertRealPathWithinBase(realBase, baseDir, rel)
231
+ const abs = join(baseDir, rel)
232
+ const buf = readFileSync(abs)
233
+ if (withIntegrity) integrities.set(rel, sha512integrity(buf))
234
+ const format = sourceFormat(abs, buf)
235
+ // A binary plist can't be stored as the UTF-8 string its 'xml' format implies, so it is NOT source: it falls through to the resource branch (opaque base64).
236
+ if (format !== undefined && !isBinaryPlist(rel, buf)) {
237
+ // Source is stored as a UTF-8 string, so non-UTF-8 bytes would lossily diverge from the file on disk.
238
+ if (isUtf8(buf)) codeFiles.set(rel, { content: buf.toString('utf8'), format, executable })
239
+ else nonUtf8.push({ rel, format })
240
+ } else if (resources.has(pathExt(rel) || basename(rel).toLowerCase())) {
241
+ const utf8 = isUtf8(buf)
242
+ resourceFiles.set(rel, { content: utf8 ? buf.toString('utf8') : buf.toString('base64'), format: utf8 ? 'resource' : 'resource:base64', executable })
243
+ } else {
244
+ undeclared.push(rel)
245
+ }
246
+ }
247
+ if (missing.length + undeclared.length + nonUtf8.length > 0) throw validationError({ missing, undeclared, nonUtf8 })
248
+ return { codeFiles, resourceFiles, integrities }
249
+ }
250
+
251
+ // GLOB the listed paths, FILTERING the auto-excluded set out of what a sweep finds (see
252
+ // expandDirectories) -> VALIDATE the whole surviving set -> only then ADD it to the target
253
+ // bundle(s), add-if-missing. A stasis.lock.json is updated only when one already exists.
254
+ export function addCommand({ cwd = process.cwd(), entries, logLabel = 'stasis-core' } = {}) {
255
+ if (!Array.isArray(entries) || entries.length === 0) {
256
+ throw new Error('add: at least one file is required')
257
+ }
258
+ const baseDir = resolve(cwd)
259
+ const realBase = realpathSync(baseDir)
260
+ const { bundleFile, resourcesBundleFile, resources, brotliQuality } = readAddConfig(baseDir)
261
+
262
+ const rootPkg = readJson(join(baseDir, 'package.json')) ?? {}
263
+ const workspaceName = rootPkg.name ?? 'workspace'
264
+ const workspaceVersion = rootPkg.version ?? '0.0.0'
265
+
266
+ // Lockfile updated only if one already exists (never created); hash packed bytes to match a frozen run.
267
+ const lockPath = join(baseDir, LOCK_FILE)
268
+ const hasLock = existsSync(lockPath)
269
+
270
+ // The CONFIGURED bundle targets, project-relative: a sweep must never attest an artifact this very
271
+ // run is writing, and a target can be named anything (`dist/code.br`), which isAutoExcludedFile's
272
+ // by-name rule can't recognize (it does cover the lockfile). One configured outside the project
273
+ // yields a '..' path, which no swept path can equal.
274
+ const outputs = new Set([bundleFile, resourcesBundleFile]
275
+ .filter((file) => file !== undefined)
276
+ .map((file) => toPosix(relative(baseDir, resolve(baseDir, file)))))
277
+
278
+ // `excluded` is counted in the summary below rather than dropped silently.
279
+ const { files, excluded } = expandDirectories(baseDir, normalizeEntries(entries, cwd), outputs)
280
+ if (files.size === 0) {
281
+ throw new Error(`add: no files to add (directory entries matched ${excluded.size === 0
282
+ ? 'nothing' : `only auto-excluded files: ${listPaths(excluded)}`})`)
283
+ }
284
+
285
+ const { codeFiles, resourceFiles, integrities } = validateFiles({ baseDir, realBase, files, resources, withIntegrity: hasLock })
286
+
287
+ // ADD step: every target's merge is computed first, then the writes run -- see prepareBundleFile.
288
+ const summary = []
289
+ const writes = []
290
+ const repo = detectRepo(baseDir)
291
+ const planTarget = (target, entriesForTarget, kind) => {
292
+ if (entriesForTarget.size === 0) return
293
+ const { write, counts } = prepareBundleFile(baseDir, target, assembleBundle(baseDir, entriesForTarget, workspaceName, workspaceVersion, repo), brotliQuality)
294
+ writes.push(write)
295
+ summary.push(`+${counts.added} ${kind} (${counts.total} total) -> ${counts.path}`)
296
+ }
297
+ if (resourcesBundleFile) {
298
+ planTarget(bundleFile, codeFiles, 'source')
299
+ planTarget(resourcesBundleFile, resourceFiles, 'resource')
300
+ } else {
301
+ const kind = codeFiles.size > 0 && resourceFiles.size > 0 ? 'file' : resourceFiles.size > 0 ? 'resource' : 'source'
302
+ planTarget(bundleFile, new Map([...codeFiles, ...resourceFiles]), kind)
303
+ }
304
+
305
+ // One lockfile attests both split targets, so merge in every packed file's integrity (code + resources together).
306
+ if (hasLock) {
307
+ const allFiles = new Map([...codeFiles, ...resourceFiles])
308
+ const lockAdd = bundleToLockfile(assembleBundle(baseDir, allFiles, workspaceName, workspaceVersion), integrities)
309
+ const { write, counts } = prepareLockfile(lockPath, lockAdd)
310
+ writes.push(write)
311
+ summary.push(`+${counts.added} (${counts.total} total) -> ${LOCK_FILE}`)
312
+ }
313
+ if (excluded.size > 0) summary.push(`skipped ${excluded.size} auto-excluded`)
314
+
315
+ for (const write of writes) write()
316
+ console.warn(`[${logLabel}] add: ${summary.join('; ')}`)
317
+ }