@exodus/stasis-core 1.0.0-beta.14 → 1.0.0-beta.16

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@exodus/stasis-core",
3
- "version": "1.0.0-beta.14",
3
+ "version": "1.0.0-beta.16",
4
4
  "description": "Zero-dependency stasis runtime",
5
5
  "type": "module",
6
6
  "exports": {
@@ -17,6 +17,7 @@
17
17
  "./util": "./src/util.js",
18
18
  "./brotli": "./src/brotli.js",
19
19
  "./state-util": "./src/state-util.js",
20
+ "./policy": "./src/policy.js",
20
21
  "./prune": "./src/prune.js",
21
22
  "./cli": "./src/cli.js"
22
23
  },
@@ -36,6 +37,7 @@
36
37
  "src/loader.js",
37
38
  "src/lockfile.js",
38
39
  "src/package.cjs",
40
+ "src/policy.js",
39
41
  "src/prune.js",
40
42
  "src/shard.js",
41
43
  "src/state.js",
package/src/add.js CHANGED
@@ -1,92 +1,63 @@
1
1
  import { isUtf8 } from 'node:buffer'
2
2
  import * as fs from 'node:fs'
3
- import { basename, dirname, extname, join, posix, relative, resolve, sep } from 'node:path'
3
+ import { dirname, extname, join, relative, resolve, sep } from 'node:path'
4
4
 
5
5
  import { Bundle } from './bundle.js'
6
6
  import { Lockfile } from './lockfile.js'
7
7
  import { compressBundleText, parseBundleBytes } from './brotli.js'
8
8
  import { detectRepo, normalizeEntries, packageLookup, packageType, readJson, statStrict } from './bundle-util.js'
9
9
  import { diskHost } from './host.js'
10
+ import { linksOn, parsePolicy, recordedIn } from './policy.js'
10
11
  import { canonicalizePath, sha512integrity } from './state-util.js'
11
- import { assertRealPathWithinBase, classifyFormat, fileInBucket, hasNodeModulesSegment, isAutoExcludedDir, isAutoExcludedFile, isBinaryPlist, isBrotliQuality, isExecutableMode, moduleInfo, parseResourcesOption, pathExt, sortPaths, splitNodeModulesPath, toPosix, withMetadataOf } from './util.js'
12
+ import { assertRealPathWithinBase, attestsAny, BUNDLE_FILE, classifyFormat, CONFIG_FILE, extraPattern, fileInBucket, hasNodeModulesSegment, heldToAccounts, inResources, installedAccounts, isAutoExcludedDir, isAutoExcludedFile, isBinaryPlist, isBrotliQuality, isExecutableMode, LOCK_FILE, memoized, moduleInfo, parseResourcesOption, sortedByPath, splitNodeModulesPath, toPosix, withAttestedOf, withMetadataOf } from './util.js'
12
13
 
13
- // Snapshotted before `stasis run --fs` patches node:fs: State#includeExtra matches its outputs with
14
- // these at write (outputMatcher), which must read the real disk, not be captured as the program's
15
- // reads. It sweeps `extra` through its host, which the disk's snapshots too.
14
+ // Snapshotted before `stasis run --fs` patches node:fs: outputMatcher must read the real disk, not be captured.
16
15
  const { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } = fs
17
16
 
18
- const CONFIG_FILE = 'stasis.config.json'
19
- const LOCK_FILE = 'stasis.lock.json'
20
-
21
- // A `.js`/`.ts` follows its package `type` (LIMITATION: none falls back to commonjs -- use `.mjs`/`.cjs`
22
- // or set `type` when the module system matters). Any other name is classifyFormat's call: a format,
23
- // null for a JS-family file (`.jsx`/`.tsx`: source attested with no loader format, as the runtime
24
- // records one), undefined when unrecognized. Its package.json is read through `host`.
25
- function sourceFormat(absFile, content, host) {
17
+ // LIMITATION: a `.js`/`.ts` in a package with no `type` is commonjs; use `.mjs`/`.cjs` or set it.
18
+ function sourceFormat(absFile, content, host, kept) {
26
19
  const ext = extname(absFile).toLowerCase()
27
- if (ext === '.js' || ext === '.ts') return `${packageType(absFile, host) ?? 'commonjs'}${ext === '.ts' ? '-typescript' : ''}`
20
+ if (ext === '.js' || ext === '.ts') return `${packageType(absFile, host, kept) ?? 'commonjs'}${ext === '.ts' ? '-typescript' : ''}`
28
21
  return classifyFormat(absFile, { content })
29
22
  }
30
23
 
31
- // File and non-empty package counts of a bundle or lockfile.
32
- const tally = (artifact) => {
33
- let files = 0
34
- let packages = 0
35
- for (const m of artifact.modules.values()) {
36
- const n = Object.keys(m.files).length
37
- if (n > 0) {
38
- files += n
39
- packages += 1
40
- }
41
- }
42
- return { files, packages }
43
- }
24
+ const fileCount = (artifact) => artifact.modules.values().reduce((n, { files }) => n + Object.keys(files).length, 0)
44
25
 
45
26
  function readAddConfig(baseDir) {
46
27
  const cfg = readJson(join(baseDir, CONFIG_FILE))
47
- if (cfg === null) {
48
- throw new Error(`add requires a ${CONFIG_FILE} (its bundleFile, resourcesBundleFile, and resources are all optional)`)
49
- }
28
+ if (cfg === null) throw new Error(`add requires a ${CONFIG_FILE} (its bundleFile, resourcesBundleFile, and resources are all optional)`)
50
29
  const resources = parseResourcesOption(CONFIG_FILE, cfg.resources)
51
30
  if (cfg.brotliQuality !== undefined && !isBrotliQuality(cfg.brotliQuality)) {
52
31
  throw new Error(`${CONFIG_FILE}: brotliQuality must be an integer 0..11 (got ${JSON.stringify(cfg.brotliQuality)})`)
53
32
  }
54
- const bundleFile = cfg.bundleFile ?? 'stasis.code.br'
33
+ const bundleFile = cfg.bundleFile ?? BUNDLE_FILE
55
34
  const resourcesBundleFile = cfg.resourcesBundleFile
56
- // Split targets must be distinct files (else they clobber on write); canonicalized so symlink and relative aliases are caught too.
35
+ // Distinct, else they clobber on write; canonicalized so symlink and relative aliases are caught too.
57
36
  if (resourcesBundleFile &&
58
37
  canonicalizePath(resolve(baseDir, bundleFile)) === canonicalizePath(resolve(baseDir, resourcesBundleFile))) {
59
38
  throw new Error(`${CONFIG_FILE}: bundleFile and resourcesBundleFile must name distinct paths (both resolve to ${resolve(baseDir, bundleFile)})`)
60
39
  }
61
- return { bundleFile, resourcesBundleFile, resources, brotliQuality: cfg.brotliQuality }
40
+ return { bundleFile, resourcesBundleFile, resources, brotliQuality: cfg.brotliQuality, policy: parsePolicy(CONFIG_FILE, cfg) }
62
41
  }
63
42
 
64
- // 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`.
65
- // `buckets` (dir -> module) are identities to take for a dir over the one found there: those of the
66
- // bundle the files will merge into, which may name its buckets otherwise (`solidity-bundle`, say).
67
- // Their package.json files are read through `host`.
68
- function assembleBundle(baseDir, files, workspaceName, workspaceVersion, repo, { reason = 'add', buckets = new Map(), host = diskHost } = {}) {
43
+ // With NO entries: `add` attests files, not entry points, so nothing in it runs via `--bundle=load`.
44
+ export function assembleBundle(baseDir, files, workspaceName, workspaceVersion, repo, { reason = 'add', buckets = new Map(), host = diskHost } = {}) {
69
45
  const modules = new Map()
70
46
  const formats = new Map()
71
47
  const executable = new Set()
72
- // `identity`'s name, version, ecosystem, repo and vendored (moduleInfo takes those alone); a later
73
- // file's adds the vendored package it is in.
74
- const bucketFiles = (dir, identity) => {
75
- const bucket = modules.get(dir)
76
- identity = buckets.get(dir) ?? identity
77
- modules.set(dir, bucket === undefined ? moduleInfo({ ...identity, files: Object.create(null) }) : withMetadataOf(bucket, identity))
78
- return modules.get(dir).files
79
- }
80
48
  const metaFor = packageLookup(baseDir, { host })
81
49
 
82
50
  for (const [rel, { content, format, executable: isExec }] of files) {
83
51
  const meta = metaFor(rel)
84
- // A node_modules file whose nearest package.json is the workspace root (or none at all) is a misconfigured dep -- refuse.
85
52
  if (splitNodeModulesPath(rel) !== null && !(meta && hasNodeModulesSegment(meta.pkgDir))) {
86
53
  throw new Error(`add: no package.json with name+version found for ${rel}`)
87
54
  }
88
- const [dir, identity] = meta ? [meta.pkgDir, meta] : ['.', { name: workspaceName, version: workspaceVersion }]
89
- bucketFiles(dir, identity)[fileInBucket(dir, rel)] = content
55
+ const dir = meta ? meta.pkgDir : '.'
56
+ const identity = buckets.get(dir) ?? meta ?? { name: workspaceName, version: workspaceVersion }
57
+ const bucket = modules.get(dir)
58
+ const info = bucket === undefined ? moduleInfo({ ...identity, files: Object.create(null) }) : withMetadataOf(bucket, identity)
59
+ modules.set(dir, info)
60
+ info.files[fileInBucket(dir, rel)] = content
90
61
  if (format != null) formats.set(rel, format)
91
62
  if (isExec) executable.add(rel)
92
63
  }
@@ -94,56 +65,50 @@ function assembleBundle(baseDir, files, workspaceName, workspaceVersion, repo, {
94
65
  return new Bundle({ config: { scope: 'full' }, entries: new Set(), modules, formats, imports: new Map(), executable, repo }).withReason(reason)
95
66
  }
96
67
 
97
- // Merge add-if-missing into any existing bundle (divergent bytes for an attested path throw -- see
98
- // mergeModuleMaps), returning the write as a thunk so every target's conflicts surface before the
99
- // first byte lands and an aborted `add` leaves the project untouched. Serializing INSIDE the thunk
100
- // keeps peak memory at one target's bytes rather than every target's at once.
101
- function prepareBundleFile(baseDir, targetPath, bundle, brotliQuality) {
102
- const abs = resolve(baseDir, targetPath)
103
- let mergedFrom
104
- if (existsSync(abs)) {
105
- let existing
106
- try {
107
- existing = parseBundleBytes(readFileSync(abs))
108
- } catch (cause) {
109
- throw new Error(`add: failed to read the existing bundle at ${targetPath}`, { cause })
110
- }
111
- mergedFrom = tally(existing).files
112
- bundle = existing.merge(bundle)
68
+ // Each artifact's attested packages are held to the others' and to the install. The attest(existing, added, companion)
69
+ // returned has `added` attest as `existing`, else its split half `companion`, the others, the install.
70
+ function heldToInstall(baseDir, artifacts) {
71
+ const known = new Map()
72
+ for (const [path, artifact] of artifacts) {
73
+ const attested = new Map([...artifact.modules].filter(([, info]) => attestsAny(info)))
74
+ for (const [dir, info] of attested) known.set(dir, known.has(dir) ? withMetadataOf(known.get(dir), info, `${path}: module '${dir}' (against the other artifacts)`) : info)
75
+ heldToAccounts(attested, installedAccounts(attested, baseDir), `${path}: `)
113
76
  }
114
- const { files, packages } = tally(bundle)
115
- return {
116
- write: () => {
117
- mkdirSync(dirname(abs), { recursive: true })
118
- writeFileSync(abs, compressBundleText(bundle.serialize(), brotliQuality))
119
- },
120
- counts: { path: targetPath, total: files, packages, added: mergedFrom === undefined ? files : files - mergedFrom },
77
+ return (existing, added, companion) => {
78
+ for (const [dir, account] of installedAccounts(added.modules, baseDir)) {
79
+ if (!account.locked) added.modules.set(dir, withAttestedOf(added.modules.get(dir), existing?.modules.get(dir) ?? companion?.modules.get(dir) ?? known.get(dir) ?? account))
80
+ }
81
+ return added
121
82
  }
122
83
  }
123
84
 
124
- // Companion Lockfile: the bundle's shape with each file's content swapped for its on-disk integrity, so `--lock=frozen` matches.
125
- const bundleToLockfile = (bundle, integrities) => Lockfile.fromBundle(bundle, (file) => integrities.get(file))
126
-
127
- // Merge into the project's stasis.lock.json (strict: divergent bytes throw), deferring the write like
128
- // prepareBundleFile so a conflict here doesn't leave the bundles updated.
129
- function prepareLockfile(lockPath, lockAdd) {
130
- let existing
85
+ function existingOf(what, parse) {
131
86
  try {
132
- existing = Lockfile.parse(readFileSync(lockPath, 'utf8'))
87
+ return parse()
133
88
  } catch (cause) {
134
- throw new Error(`add: failed to read the existing ${LOCK_FILE}`, { cause })
89
+ throw new Error(`add: failed to read the existing ${what}`, { cause })
90
+ }
91
+ }
92
+
93
+ // A thunk, so every target's conflicts surface before a byte lands; serializing in it keeps peak memory at one target's.
94
+ function prepareBundleFile(baseDir, targetPath, bundle, brotliQuality, check, existing) {
95
+ check?.(bundle)
96
+ const abs = resolve(baseDir, targetPath)
97
+ let before = 0
98
+ if (existing) {
99
+ check?.(existing, recordedIn(targetPath))
100
+ before = fileCount(existing)
101
+ bundle = existing.merge(bundle)
135
102
  }
136
- const before = tally(existing).files
137
- const merged = existing.merge(lockAdd)
138
- const total = tally(merged).files
139
- return { write: () => writeFileSync(lockPath, merged.serialize()), counts: { total, added: total - before } }
103
+ const total = fileCount(bundle)
104
+ const write = () => {
105
+ mkdirSync(dirname(abs), { recursive: true })
106
+ writeFileSync(abs, compressBundleText(bundle.serialize(), brotliQuality))
107
+ }
108
+ return { write, total, added: total - before }
140
109
  }
141
110
 
142
- // Whether a project-relative path, with its stats (undefined when missing), is one of `outputs`
143
- // (project-relative): by name, or as the same file under another, a symlink or hard link to it -- its
144
- // device and inode, which a write rewrites in place. Stats as numbers can round a large inode
145
- // (Windows file ids), so a match on those is settled exactly (bigint), never taken on its own. The
146
- // outputs are the disk's, where a run writes them: a sweep of another host's tree has none.
111
+ // By name, or dev+inode (a link to one, which a write rewrites in place), confirmed in bigint: a number rounds big inodes.
147
112
  function outputMatcher(baseDir, outputs) {
148
113
  const exact = new Set()
149
114
  const rounded = new Set()
@@ -161,10 +126,7 @@ function outputMatcher(baseDir, outputs) {
161
126
  }
162
127
  }
163
128
 
164
- // `host`'s glob of `pattern` under `cwd` (Node's fs.globSync, the disk's or a Vfs's), its matches
165
- // relative to it, walking into none `exclude` takes (given the path relative to `baseDir`,
166
- // '/'-joined), which leaves one out where its `**` meets it alone. A visited name is checked as
167
- // spelled: one holding `\` is for the caller to refuse where it is kept, not here.
129
+ // Node leaves out a path `exclude` takes only where its `**` meets it, so it is asked of each '/'-joined project path.
168
130
  function globPaths(host, pattern, cwd, baseDir, exclude) {
169
131
  const projectPath = (path) => {
170
132
  const rel = relative(baseDir, path)
@@ -173,20 +135,10 @@ function globPaths(host, pattern, cwd, baseDir, exclude) {
173
135
  return host.glob(pattern, { cwd, exclude: exclude && ((path) => exclude(projectPath(path))) })
174
136
  }
175
137
 
176
- // GLOB + FILTER: expand each directory entry into the files under it (recursive glob), dropping the
177
- // auto-excluded set from what a sweep FINDS -- dir rules on the segments BELOW the named root (`add
178
- // src/examples` sweeps the dir it was pointed at, `add src` skips one it merely found), file rules
179
- // by name plus the caller's `outputs` (this run's own write targets, by name or alias: outputMatcher).
180
- // A path the caller NAMED is always kept (naming is the override; a missing one keeps stats undefined
181
- // so validation reports it) -- unless `keepNamedOutputs` is false, then one of `outputs` never is --
182
- // and inclusion is monotone: a nearer root's sweep can only ever see FEWER excluded segments,
183
- // so a path any entry keeps stays kept -- `add src src/examples` includes the subtree it names in
184
- // either order. `stats` is the walk's own stat, reused by validation. Gotcha: `**/*` skips dotfiles
185
- // (.env, .git/...) -- name them explicitly. A project-relative path `exclude` takes is dropped, named
186
- // or swept, with everything under it: a named path below one too, and a directory it takes is never
187
- // walked (globPaths). Paths are read through `host`, stat'ed as real stat answers (statStrict).
138
+ // A sweep drops what it FINDS auto-excluded: dir rules below the named root (`add src/examples` sweeps it, `add src`
139
+ // skips it), file rules by name and to `outputs`. A path `exclude` takes goes, named or swept, with all under it.
188
140
  function expandDirectories(baseDir, rels, outputs, { keepNamedOutputs = true, exclude, host = diskHost } = {}) {
189
- const files = new Map() // rel -> stats
141
+ const files = new Map() // rel -> stats, the walk's own, reused by validation
190
142
  const excluded = new Set()
191
143
  const isOutput = outputMatcher(baseDir, outputs)
192
144
  for (const rel of rels) {
@@ -194,11 +146,13 @@ function expandDirectories(baseDir, rels, outputs, { keepNamedOutputs = true, ex
194
146
  if (exclude !== undefined && rel.split('/').some((_, i, segments) => exclude(segments.slice(0, i + 1).join('/')))) continue
195
147
  const dirAbs = join(baseDir, rel)
196
148
  const stats = statStrict(host, dirAbs, rel) ?? undefined
149
+ // A NAMED path is kept (naming is the override; a missing one keeps undefined stats for validation to report).
197
150
  if (stats === undefined || !stats.isDirectory()) {
198
151
  if (keepNamedOutputs || !isOutput(rel, stats)) files.set(rel, stats)
199
152
  continue
200
153
  }
201
154
  const found = []
155
+ // Gotcha: `**/*` skips dotfiles (.env, .git/...); they must be named explicitly.
202
156
  for (const match of globPaths(host, '**/*', dirAbs, baseDir, exclude)) {
203
157
  const fileAbs = join(dirAbs, match)
204
158
  const fileRel = relative(baseDir, fileAbs)
@@ -206,26 +160,23 @@ function expandDirectories(baseDir, rels, outputs, { keepNamedOutputs = true, ex
206
160
  const fileStats = statStrict(host, fileAbs, fileRel) ?? undefined
207
161
  if (fileStats?.isFile()) found.push([toPosix(fileRel), match, fileStats])
208
162
  }
209
- // Sorted so the sweep is deterministic regardless of readdir order: artifact bytes are
210
- // canonicalized by serialize() either way, but multi-file diagnostics keep a stable order.
211
- for (const [file, match, fileStats] of found.toSorted(([a], [b]) => sortPaths(a, b))) {
212
- // Node's glob holds `exclude` to its `**` alone: a file below the directory swept still
213
- // matches the `*` after it (a directory it takes is never walked).
163
+ // Sorted, whatever the readdir order, so multi-file diagnostics keep a stable order.
164
+ for (const [file, match, fileStats] of sortedByPath(found, ([path]) => path)) {
165
+ // Node's glob holds `exclude` to its `**` alone: a file below the directory swept still matches the `*` after it.
214
166
  if (exclude?.(file)) continue
215
167
  if (toPosix(match).split('/').slice(0, -1).some(isAutoExcludedDir)
216
168
  || isOutput(file, fileStats) || isAutoExcludedFile(file)) excluded.add(file)
217
169
  else files.set(file, fileStats)
218
170
  }
219
171
  }
220
- // A path any entry kept can't count as skipped -- another root's sweep may have re-flagged it.
172
+ // Inclusion is monotone: a path any entry kept stays kept, so `add src src/examples` keeps the subtree in either order.
221
173
  for (const file of files.keys()) excluded.delete(file)
222
174
  return { files, excluded }
223
175
  }
224
176
 
225
- const listPaths = (rels) => [...rels].toSorted(sortPaths).join(', ')
177
+ const listPaths = (rels) => sortedByPath(rels).join(', ')
226
178
 
227
- // One error for every file validation rejected, so a directory sweep names all of them at once
228
- // instead of one per re-run. A lone offender keeps its exact standalone message. `label` prefixes it.
179
+ // One error for every file validation rejected, so a sweep names all of them at once; a lone offender keeps its own message.
229
180
  export function validationError({ missing, undeclared, nonUtf8 }, label) {
230
181
  const phrase = (items, one, many) => (items.length === 1 ? [one(items[0])] : items.length > 1 ? [many(items)] : [])
231
182
  const withFormat = (format) => (format == null ? '' : ` (format '${format}')`)
@@ -244,47 +195,30 @@ export function validationError({ missing, undeclared, nonUtf8 }, label) {
244
195
  return new Error(`${label}: ${parts.join('; ')}`)
245
196
  }
246
197
 
247
- // stasis.config.json's `extra` patterns, expanded as a shell expands `stasis add`'s arguments: each
248
- // by Node's glob (whose `*` skips dotfiles, as the shell's does), a pattern matching nothing standing
249
- // for itself as it does without bash's nullglob (so a missing path is reported missing), then each
250
- // path as `add` takes it (expandDirectories): a file named or matched is kept, a directory swept.
251
- // One of `outputs`, the files this very run writes, is never kept, named, matched (`dist/*`) or
252
- // under another name (outputMatcher). A `!` entry (`!ios/Pods`, `!**/xcuserdata`) is no path: it
253
- // takes out every path its pattern matches, in any order of the entries, along with everything under
254
- // one that is a directory, which is then never walked, whether by a pattern's expansion or a sweep:
255
- // a pattern whose every match is excluded matches nothing. One matching nothing is no error.
256
- // `baseDir` is read through `host`, globbed and matched as Node globs and matches the disk
257
- // (fs.globSync, path.matchesGlob), whichever host's it is.
198
+ // As a shell expands `stasis add`'s arguments: Node's glob (its `*` skips dotfiles), a pattern matching nothing kept as
199
+ // itself (no nullglob: a missing path is reported), then each path as `add` takes it, but one of `outputs`.
258
200
  export function expandExtra(baseDir, patterns, outputs, host = diskHost) {
259
- // Normalized as the paths they're matched against are: no `./`, no trailing `/`.
260
- const exclusions = patterns.filter((pattern) => pattern.startsWith('!')).map((pattern) => posix.normalize(pattern.slice(1)).replace(/\/+$/u, ''))
261
- // Each path once: a walk asks of it, a sweep again, and a named path of every directory above it,
262
- // where the disk's path.matchesGlob parses each pattern anew.
263
- const excluded = new Map()
264
- const exclude = exclusions.length === 0 ? undefined : (rel) => {
265
- if (!excluded.has(rel)) excluded.set(rel, exclusions.some((pattern) => host.matchesGlob(rel, pattern)))
266
- return excluded.get(rel)
267
- }
201
+ // A `!` entry takes out every match and all under it (never walked), in any entry order.
202
+ const exclusions = patterns.filter((pattern) => pattern.startsWith('!')).map(extraPattern)
203
+ // Memoized: a walk asks of each path, a sweep again, and a named path of every directory above it.
204
+ const exclude = exclusions.length === 0 ? undefined : memoized((rel) => exclusions.some((pattern) => host.matchesGlob(rel, pattern)))
268
205
  const entries = patterns.filter((pattern) => !pattern.startsWith('!')).flatMap((pattern) => {
269
206
  const matches = globPaths(host, pattern, baseDir, baseDir, exclude)
270
- return matches.length === 0 ? [pattern] : matches.toSorted(sortPaths)
207
+ return matches.length === 0 ? [pattern] : sortedByPath(matches)
271
208
  })
272
209
  return expandDirectories(baseDir, normalizeEntries(entries, baseDir), outputs, { keepNamedOutputs: false, exclude, host })
273
210
  }
274
211
 
275
- // VALIDATE step: classify the WHOLE set -- each file recognized source or a declared resource --
276
- // before a single target is touched, collecting every offender into one error. `files` is the glob
277
- // step's rel -> stats map (stats undefined = not on disk). Containment is the one rule NOT collected:
278
- // a symlink escaping the root is a security invariant, so it fails closed on the spot. Bytes are
279
- // hashed only when there's a lockfile to receive the integrities (`withIntegrity`). `label` prefixes the error.
280
- // Files are read through `host`.
281
- function validateFiles({ baseDir, realBase, files, resources, withIntegrity, label = 'add', host = diskHost }) {
212
+ // The WHOLE set is classified before any target is touched; only a symlink escaping the root fails on the spot.
213
+ export function validateFiles({ baseDir, realBase, files, resources, withIntegrity, label = 'add', host = diskHost }) {
282
214
  const codeFiles = new Map()
283
215
  const resourceFiles = new Map()
284
216
  const integrities = new Map()
285
217
  const missing = []
286
218
  const undeclared = []
287
219
  const nonUtf8 = []
220
+ const types = new Map()
221
+ const kept = (path, read) => (types.has(path) ? types.get(path) : types.set(path, read()).get(path))
288
222
  for (const [rel, stats] of files) {
289
223
  if (stats === undefined) {
290
224
  missing.push(rel)
@@ -295,13 +229,13 @@ function validateFiles({ baseDir, realBase, files, resources, withIntegrity, lab
295
229
  const abs = join(baseDir, rel)
296
230
  const buf = host.readFile(abs)
297
231
  if (withIntegrity) integrities.set(rel, sha512integrity(buf))
298
- const format = sourceFormat(abs, buf, host)
299
- // 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).
232
+ const format = sourceFormat(abs, buf, host, kept)
233
+ // A binary plist can't be stored as the UTF-8 string its 'xml' format implies: a resource (opaque base64).
300
234
  if (format !== undefined && !isBinaryPlist(rel, buf)) {
301
235
  // Source is stored as a UTF-8 string, so non-UTF-8 bytes would lossily diverge from the file on disk.
302
236
  if (isUtf8(buf)) codeFiles.set(rel, { content: buf.toString('utf8'), format, executable })
303
237
  else nonUtf8.push({ rel, format })
304
- } else if (resources.has(pathExt(rel) || basename(rel).toLowerCase())) {
238
+ } else if (inResources(rel, resources)) {
305
239
  const utf8 = isUtf8(buf)
306
240
  resourceFiles.set(rel, { content: utf8 ? buf.toString('utf8') : buf.toString('base64'), format: utf8 ? 'resource' : 'resource:base64', executable })
307
241
  } else {
@@ -312,54 +246,27 @@ function validateFiles({ baseDir, realBase, files, resources, withIntegrity, lab
312
246
  return { codeFiles, resourceFiles, integrities }
313
247
  }
314
248
 
315
- // The files stasis.config.json's `extra` names under `baseDir` (expandExtra), packed as `add` packs
316
- // them, for `stasis bundle` to merge into `bundle`, one built there without a State (always full
317
- // scope): those it doesn't carry already (its own record of a file stands), in its buckets where it
318
- // has them. `outputs` are the project-relative paths the build writes, never swept in. The files
319
- // are read through `host`, the disk by default.
320
- // -> { bundle, lockfile } of the `extra` consumer (null when there is nothing to add), and
321
- // `carried`: the files named that `bundle` carries already, the `extra` consumer's too
322
- export function extraArtifacts({ baseDir, patterns, resources, bundle, outputs = new Set(), host = diskHost }) {
323
- const named = expandExtra(baseDir, patterns, outputs, host).files
324
- // Bundle#sources builds its Map afresh on each read: once.
325
- const bundled = bundle.sources
326
- const carried = [...named.keys()].filter((rel) => bundled.has(rel))
327
- const files = new Map([...named].filter(([rel]) => !bundled.has(rel)))
328
- if (files.size === 0) return { bundle: null, lockfile: null, carried }
329
- const { codeFiles, resourceFiles, integrities } = validateFiles({ baseDir, realBase: host.realpath(baseDir), files, resources, withIntegrity: true, label: 'extra', host })
330
- const rootPkg = readJson(join(baseDir, 'package.json'), host) ?? {}
331
- const extra = assembleBundle(baseDir, new Map([...codeFiles, ...resourceFiles]), rootPkg.name ?? 'workspace', rootPkg.version ?? '0.0.0', undefined, { reason: 'extra', buckets: bundle.modules, host })
332
- return { bundle: extra, lockfile: bundleToLockfile(extra, integrities), carried }
333
- }
334
-
335
- // GLOB the listed paths, FILTERING the auto-excluded set out of what a sweep finds (see
336
- // expandDirectories) -> VALIDATE the whole surviving set -> only then ADD it to the target
337
- // bundle(s), add-if-missing. A stasis.lock.json is updated only when one already exists.
338
249
  export function addCommand({ cwd = process.cwd(), entries, logLabel = 'stasis-core' } = {}) {
339
- if (!Array.isArray(entries) || entries.length === 0) {
340
- throw new Error('add: at least one file is required')
341
- }
250
+ if (!Array.isArray(entries) || entries.length === 0) throw new Error('add: at least one file is required')
342
251
  const baseDir = resolve(cwd)
343
252
  const realBase = realpathSync(baseDir)
344
- const { bundleFile, resourcesBundleFile, resources, brotliQuality } = readAddConfig(baseDir)
253
+ const { bundleFile, resourcesBundleFile, resources, brotliQuality, policy } = readAddConfig(baseDir)
254
+ const links = linksOn(baseDir)
255
+ const check = policy && ((artifact, hint) => policy.assertArtifact(artifact, { hint, links }))
345
256
 
346
257
  const rootPkg = readJson(join(baseDir, 'package.json')) ?? {}
347
258
  const workspaceName = rootPkg.name ?? 'workspace'
348
259
  const workspaceVersion = rootPkg.version ?? '0.0.0'
349
260
 
350
- // Lockfile updated only if one already exists (never created); hash packed bytes to match a frozen run.
351
261
  const lockPath = join(baseDir, LOCK_FILE)
352
262
  const hasLock = existsSync(lockPath)
353
263
 
354
- // The CONFIGURED bundle targets, project-relative: a sweep must never attest an artifact this very
355
- // run is writing, and a target can be named anything (`dist/code.br`), which isAutoExcludedFile's
356
- // by-name rule can't recognize (it does cover the lockfile). One configured outside the project
357
- // yields a '..' path, which no swept path can equal.
264
+ // A sweep must never attest what this run writes, and isAutoExcludedFile's by-name rule can't know a target named
265
+ // `dist/code.br`. One outside the project yields a '..' path, which no swept path can equal.
358
266
  const outputs = new Set([bundleFile, resourcesBundleFile]
359
267
  .filter((file) => file !== undefined)
360
268
  .map((file) => toPosix(relative(baseDir, resolve(baseDir, file)))))
361
269
 
362
- // `excluded` is counted in the summary below rather than dropped silently.
363
270
  const { files, excluded } = expandDirectories(baseDir, normalizeEntries(entries, cwd), outputs)
364
271
  if (files.size === 0) {
365
272
  throw new Error(`add: no files to add (directory entries matched ${excluded.size === 0
@@ -368,31 +275,42 @@ export function addCommand({ cwd = process.cwd(), entries, logLabel = 'stasis-co
368
275
 
369
276
  const { codeFiles, resourceFiles, integrities } = validateFiles({ baseDir, realBase, files, resources, withIntegrity: hasLock })
370
277
 
371
- // ADD step: every target's merge is computed first, then the writes run -- see prepareBundleFile.
278
+ // Every target's merge is computed first, then the writes run -- see prepareBundleFile.
372
279
  const summary = []
373
280
  const writes = []
374
281
  const repo = detectRepo(baseDir)
282
+ // Each artifact is read before a file is added to any: what one attests of a package is held of the others too.
283
+ const bundleAt = (file, abs = resolve(baseDir, file)) => (existsSync(abs) ? existingOf(`bundle at ${file}`, () => parseBundleBytes(readFileSync(abs))) : undefined)
284
+ const bundles = new Map([bundleFile, resourcesBundleFile].filter(Boolean).map((file) => [file, bundleAt(file)]))
285
+ const lock = hasLock ? existingOf(LOCK_FILE, () => Lockfile.parse(readFileSync(lockPath, 'utf8'))) : undefined
286
+ const attest = heldToInstall(baseDir, [...bundles, [LOCK_FILE, lock]].filter(([, artifact]) => artifact))
375
287
  const planTarget = (target, entriesForTarget, kind) => {
376
288
  if (entriesForTarget.size === 0) return
377
- const { write, counts } = prepareBundleFile(baseDir, target, assembleBundle(baseDir, entriesForTarget, workspaceName, workspaceVersion, repo), brotliQuality)
289
+ const existing = bundles.get(target)
290
+ const companion = bundles.get(target === bundleFile ? resourcesBundleFile : bundleFile)
291
+ const added = attest(existing, assembleBundle(baseDir, entriesForTarget, workspaceName, workspaceVersion, repo), companion)
292
+ const { write, total, added: count } = prepareBundleFile(baseDir, target, added, brotliQuality, check, existing)
378
293
  writes.push(write)
379
- summary.push(`+${counts.added} ${kind} (${counts.total} total) -> ${counts.path}`)
294
+ summary.push(`+${count} ${kind} (${total} total) -> ${target}`)
380
295
  }
296
+ const allFiles = new Map([...codeFiles, ...resourceFiles])
381
297
  if (resourcesBundleFile) {
382
298
  planTarget(bundleFile, codeFiles, 'source')
383
299
  planTarget(resourcesBundleFile, resourceFiles, 'resource')
384
300
  } else {
385
301
  const kind = codeFiles.size > 0 && resourceFiles.size > 0 ? 'file' : resourceFiles.size > 0 ? 'resource' : 'source'
386
- planTarget(bundleFile, new Map([...codeFiles, ...resourceFiles]), kind)
302
+ planTarget(bundleFile, allFiles, kind)
387
303
  }
388
304
 
389
- // One lockfile attests both split targets, so merge in every packed file's integrity (code + resources together).
305
+ // One lockfile attests both split targets, so it takes every packed file's integrity (code + resources).
390
306
  if (hasLock) {
391
- const allFiles = new Map([...codeFiles, ...resourceFiles])
392
- const lockAdd = bundleToLockfile(assembleBundle(baseDir, allFiles, workspaceName, workspaceVersion), integrities)
393
- const { write, counts } = prepareLockfile(lockPath, lockAdd)
394
- writes.push(write)
395
- summary.push(`+${counts.added} (${counts.total} total) -> ${LOCK_FILE}`)
307
+ const lockAdd = attest(lock, Lockfile.fromBundle(assembleBundle(baseDir, allFiles, workspaceName, workspaceVersion),
308
+ (file) => integrities.get(file)))
309
+ // `check` sees only what it already records: the files added were checked as the bundles'.
310
+ check?.(lock, recordedIn(LOCK_FILE))
311
+ const merged = lock.merge(lockAdd)
312
+ writes.push(() => writeFileSync(lockPath, merged.serialize()))
313
+ summary.push(`+${fileCount(merged) - fileCount(lock)} (${fileCount(merged)} total) -> ${LOCK_FILE}`)
396
314
  }
397
315
  if (excluded.size > 0) summary.push(`skipped ${excluded.size} auto-excluded`)
398
316