@exodus/stasis 1.0.0-beta.2 → 1.0.0-beta.5

package/bin/stasis.js

@@ -1,14 +1,13 @@
 #!/usr/bin/env node
 
 import { spawn } from 'node:child_process'
-import { parseArgs } from 'node:util'
 import { once } from 'node:events'
 import { fileURLToPath } from 'node:url'
-import { basename, dirname, resolve } from 'node:path'
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
 import { existsSync, realpathSync } from 'node:fs'
-import { constants as osConstants } from 'node:os'
+import { homedir, constants as osConstants } from 'node:os'
 import assert from 'node:assert/strict'
-import { parseBrotliQuality } from '@exodus/stasis-core/util'
+import { parseBrotliQuality, parseLeadingOptions, parseResourcesOption } from '@exodus/stasis-core/util'
 import pkg from '../package.json' with { type: 'json' }
 
 const argv = [...process.argv]
@@ -16,27 +15,100 @@ assert(['node', 'node.exe'].includes(basename(argv.shift())))
 assert(['node', 'node.exe'].includes(basename(process.argv0)))
 
 const jsname = argv.shift()
-const pathsEqual = (a, b) => a === b || (existsSync(a) && realpathSync(a) === b) // resolve symlinks
+const pathsEqual = (a, b) => a === b || (existsSync(a) && realpathSync(a) === b)
 assert(basename(jsname) === 'stasis' || pathsEqual(jsname, fileURLToPath(import.meta.url)))
 
 function usage(prefix = '') {
   console.error(`${prefix}\nUsage:
- stasis 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] [--mock] [--fs=(sync|async)] [--resources=ext,ext] [--brotli-quality=0..11] path/to/file.js ...
- stasis bundle [--mapping=path/to/remappings(.txt|.toml)] [--output=(path|-)] path/to/file.sol ...
- stasis bundle [--output=(path|-)] path/to/file.php ...
- stasis bundle [--scope=(node_modules|full)] [--conditions=cond1,cond2] [--mainFields=field1,field2] [--lockfile=path/to/stasis.lock.json] [--output=(path|-)] path/to/file.(js|ts) ...
- stasis bundle --metro --platforms=ios,android [--platforms=web] [--lockfile=path/to/stasis.lock.json] [--output=(path|-)] path/to/file.(js|ts) ...
- stasis bundle [--output=(path|-)] path/to/file.(sh|bash) ...
- stasis bundle [--output=(path|-)] path/to/file.rs ...
- (stasis bundle writes to stasis.code.br by default; --output=- streams to stdout;
-  --brotli-quality=0..11 tunes bundle compression for any entry language, default 11 = smallest/slowest)
- stasis build --output=(dir|file.js) [--format=(esm|cjs|iife)] [--platform=(node|browser|neutral)] [--minify] [--sourcemap] [--define=K=V ...] [--external=pkg ...] [--loader=.ext:name ...] path/to/(stasis.code.br|stasis.lock.json) [entry]
+ stasis 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] [--package-json] [--mock] [--import=module ...] [--fs=(sync|async)] [--resources=ext,ext] [--brotli-quality=0..11] path/to/file.js ...
+ (--import forwards extra preload modules (repeatable) to the node process running the entry,
+  e.g. --import=./instrument.mjs for a setup/instrumentation preload; a preload's own module
+  graph is runner infrastructure like stasis's loader itself, so it stays out of the
+  lockfile/bundle -- except modules the app graph also reaches, which are attested like any
+  other app code; with --mock, preloads run under the mock's side-effect denials, so a preload
+  that spawns helper processes cannot work there)
+ stasis bundle [--mapping=path/to/remappings(.txt|.toml)] [--manifests] [--add] [--output=(path|-)] path/to/(file.sol|dir) ...
+ (Solidity: a directory stands for every .sol file under it (a missing or empty one is skipped) --
+  "stasis bundle src test script" is what "forge build" compiles, "stasis bundle contracts" what
+  Hardhat does; imports resolve through the remappings "forge build" uses (remappings.txt,
+  foundry.toml's profile, FOUNDRY_PROFILE, lib/ auto-detection incl. dependencies' own configs),
+  else a root remappings.txt, then node_modules by file path; --mapping instead takes exactly the
+  remappings that one file lists; an import must reach a .sol file inside the project, and a
+  dependency's only other dependencies' files; --manifests also carries foundry.toml,
+  remappings.txt, foundry.lock, soldeer.lock, .gitmodules and package.json of the project and its
+  bundled dependencies, as written: RPC/Etherscan keys and URL credentials in them included)
+ stasis bundle [--add] [--output=(path|-)] path/to/file.php ...
+ stasis bundle [--scope=(node_modules|full)] [--conditions=cond1,cond2] [--mainFields=field1,field2] [--jsx] [--flow] [--typescript [--tsconfig=path/to/tsconfig.json]] [--resources=ext,ext] [--package-json] [--lockfile=path/to/stasis.lock.json] [--add] [--output=(path|-)] path/to/file.(js|ts) ...
+ stasis bundle --metro [--metro-resolver] --platforms=ios,android [--platforms=web] [--jsx] [--flow] [--typescript [--tsconfig=path/to/tsconfig.json]] [--resources=ext,ext] [--package-json] [--lockfile=path/to/stasis.lock.json] [--add] [--output=(path|-)] path/to/file.(js|ts) ...
+ stasis bundle [--add] [--output=(path|-)] path/to/file.(sh|bash) ...
+ stasis bundle [--cargo] [--cargo-features=a,b,pkg/c] [--cargo-no-default-features] [--cargo-all-features] [--cargo-target=(triple|host)] [--cargo-manifests] [--add] [--output=(path|-)] path/to/file.rs ...
+ (Rust: each crate's Cargo features are resolved from Cargo.toml/Cargo.lock like "cargo build" of the
+  entries' packages, so #[cfg(feature = ...)] code that is off stays out -- by cargo's own resolver
+  when there is a Cargo.lock (version 3 or 4; an older one stops the build), --cargo-target and every
+  locked package in-tree, by replaying the manifests otherwise (said, with why); --cargo takes the resolution
+  from "cargo metadata" instead -- it runs cargo, so only on a project you trust; the --cargo-*
+  feature flags are cargo's --features / --no-default-features / --all-features for those packages;
+  --cargo-target asks rustc for the target's cfgs so #[cfg(unix)]-style code for other targets stays
+  out too, otherwise it is all kept; --cargo-manifests also bundles each bundled package's Cargo.toml
+  and build script (a vendored crate's .cargo-checksum.json too), the workspace Cargo.toml, Cargo.lock
+  and cargo configs, as written: tokens and URL credentials in them included)
+ (writes to stasis.code.br by default; --output=- streams to stdout; --add merges into an
+  existing bundle instead of replacing it (not with --output=-); --brotli-quality=0..11, default 9;
+  --jsx parses JSX in .js/.cjs/.mjs files, e.g. React Native source (put JSX-in-TS in a .tsx file);
+  --flow strips Flow types from .js/.cjs/.mjs sources oxc can't parse (needs the optional flow-remove-types dep);
+  --typescript resolves TS the way tsc does: an import of ./x.js lands on ./x.ts when no .js is on disk
+   (likewise .mjs/.cjs -> .mts/.cts, extensionless ./x -> ./x.ts, incl. exports/imports/main targets),
+   honouring tsconfig compilerOptions.paths aliases (from ./tsconfig.json, or --tsconfig=path);
+   not with --metro-resolver;
+  --resources carries reached assets (e.g. --resources=png,svg) as resources instead of failing to bundle them;
+  --package-json auto-includes each bundled module's package.json, even ones the scan never reached)
+ stasis github-bundle --github=owner/name [--sha=commit|--tag=name] [--directory=path] [--package-manager=(pnpm|yarn1|npm|soldeer)] [--package-manager-version=version] [--lockfile=path/to/stasis.lock.json] [--output=(path|-)] [stasis bundle's options for the entries] [path/in/repo/to/(file.(js|ts)|file.sol|dir) ...]
+ (bundles a GitHub repo at a commit, or the one --tag names, its default branch's head without
+  either, as "stasis bundle" bundles a clone of it once installed: the tree is fetched (with
+  GITHUB_TOKEN where set) and held to its git tree id, and the dependencies are laid out in memory
+  from the lockfile alone, as "pnpm install --frozen-lockfile --ignore-scripts" (pnpm 9, 10, 11 or
+  12), "yarn install --frozen-lockfile --ignore-scripts" (yarn 1.22), "npm ci --ignore-scripts"
+  (npm 10.9.3 to 10.9.9, or 11.11.1 to 11.21.0) or "soldeer install" (0.12, for .sol entries)
+  would: nothing is installed, no package script runs, and every tarball and zip is held to the
+  lockfile, all cached where "stasis audit" caches. Without --package-manager, the one whose
+  lockfile installs --directory (or the repo's root), if only one's does; at
+  --package-manager-version, else at the root package.json's packageManager pin, else pnpm
+  10.33.4, yarn 1.22.22, npm 11.21.0 (which no packageManager pins) or Soldeer 0.12.0. The entries
+  are paths in --directory, or in the repo; without them, the JS files its package.json names as
+  main, exports and bin, resolved as the build resolves them (--conditions, --mainFields, --metro
+  --platforms, --typescript), or for Soldeer its .sol files directly in it, under contracts/, and
+  under its source directory (foundry.toml's src, else src/), but tests, scripts, mocks and
+  dependency or build directories; not with --metro-resolver, --cargo* or --add; writes to
+  owner-name.<commit's first 7>.stasis.code.br by default,
+  owner-name.<--directory, its / made ->.<commit's first 7>.stasis.code.br with --directory, each
+  character outside [A-Za-z0-9._-] made _, and a directory too deep to fit in 255 characters cut,
+  with a hash of it; --output=- streams to stdout)
+ stasis add path/to/(file|dir) ...
+ (adds the listed files to the project's bundle(s) with no dependency resolution;
+  a directory expands to its files. Requires a stasis.config.json (all fields optional).)
+ stasis build --output=(dir|file.js) [--format=(esm|cjs|iife)] [--platform=(node|browser|neutral|hermes)] [--babel] [--minify] [--sourcemap] [--define=K=V ...] [--external=pkg ...] [--loader=.ext:name ...] path/to/(stasis.code.br|stasis.lock.json) [entry]
+ (--platform=hermes downlevels every file for Hermes (classes, let/const, arrows, ...; via esbuild + Babel)
+  and defaults --format to iife; --babel instead transforms every file with the project's own
+  babel.config.(js|cjs|mjs|json); both resolve @babel/core and plugins from the project's dev deps)
  stasis extract [--output=path/to/dir] path/to/bundle.stasis.code.br
  stasis diff --stat [--imports] path/to/(lockfile|bundle) path/to/(lockfile|bundle)
  stasis prune [path/to/project]
- stasis audit path/to/file ...
+ stasis audit [--why|--why-deep] [--why-full] [--reason=consumer] [--repo-advisories] path/to/file ...
+ (audits the dependencies the files hold: npm packages by npm's advisories, vendored crates and
+  Composer packages by OSV's, and Soldeer packages and GitHub repos (Foundry's lib/) by those their
+  GitHub repository publishes, asked with GITHUB_TOKEN where it is set; a Composer dev version is
+  listed as not audited, no database having one;
+  --why lists, per advisory, the cross-module import paths that pull an npm package in,
+  prefixed by the bundle consumer that imports each chain at the top level, e.g. "run: a -> b -> c";
+  it skips chains whose full tail is already listed as its own chain -- --why-deep keeps them all;
+  --why-full spells every chain out instead of collapsing repeated tails to "a -> b -> ... -> d";
+  --reason=consumer shows only advisories related to that consumer, and with --why only its chains;
+  --repo-advisories also asks each package's GitHub repository for the advisories its maintainers
+  published there, before GitHub reviews them into the databases above; it needs a token in
+  GITHUB_TOKEN, and caches each package's repository for a month in the user cache dir, e.g.
+  ~/.cache/stasis)
  stasis sbom --format=(spdx|cyclonedx) [--output=(path|-)] path/to/(lockfile|bundle) ...
- (stasis sbom streams to stdout by default; --output=- is explicit stdout)
+ (streams to stdout by default; --output=- is explicit stdout)
 `.trim())
   process.exit(1)
 }
@@ -47,18 +119,20 @@ function setEnv(name, value) {
   process.env[name] = value === undefined ? '' : value
 }
 
+// The per-user cache directory, as each platform names it (XDG ignores a relative path).
+function userCacheDir() {
+  if (isAbsolute(process.env.XDG_CACHE_HOME ?? '')) return join(process.env.XDG_CACHE_HOME, 'stasis')
+  if (process.platform === 'darwin') return join(homedir(), 'Library', 'Caches', 'stasis')
+  if (process.platform === 'win32') return join(process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'), 'stasis', 'Cache')
+  return join(homedir(), '.cache', 'stasis')
+}
+
 const command = argv.shift()
 
 if (command === '-v' || command === '--version') {
   console.log(`v${pkg.version}`)
   process.exit(0)
 } else if (command === 'run') {
-  const flags = []
-  const valueFlags = new Set(['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--resources', '--brotli-quality'])
-  while (argv.length > 0 && (argv[0].startsWith('-') || valueFlags.has(flags.at(-1)))) {
-    flags.push(argv.shift())
-  }
-
   const options = {
     lock: { type: 'string', default: 'none' },
     bundle: { type: 'string', default: 'none' },
@@ -67,18 +141,17 @@ if (command === '-v' || command === '--version') {
     debug: { type: 'boolean' },
     dependencies: { type: 'boolean' },
     'child-process': { type: 'boolean' },
+    'package-json': { type: 'boolean' },
     mock: { type: 'boolean' },
+    import: { type: 'string', multiple: true },
     fs: { type: 'string' },
     resources: { type: 'string' },
     'brotli-quality': { type: 'string' },
   }
-
-  let values
-  try {
-    ({ values } = parseArgs({ args: flags, options }))
-  } catch (cause) {
-    usage(`Error: ${cause.message}`)
-  }
+  const values = parseLeadingOptions(argv, options, {
+    valueFlags: ['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--import', '--resources', '--brotli-quality'],
+    onError: usage,
+  })
   if (argv.length === 0) usage('Nothing to run: no path to file given')
   if (!['none', 'ignore', 'add', 'replace', 'frozen'].includes(values.lock)) usage('Error: invalid --lock value')
   const lock = values.lock
@@ -89,25 +162,18 @@ if (command === '-v' || command === '--version') {
   const debug = values.debug ? '1' : ''
   if (!['none', 'ignore', 'add', 'replace', 'load', 'frozen'].includes(bundle)) usage('Error: invalid --bundle value')
   if (bundleFile && bundle === 'none') usage('Error: --bundle-file requires --bundle=(add|replace|load|frozen|ignore)')
-  // Unlike --bundle-file (which is inert-but-harmless under --bundle=ignore, so Config allows
-  // it), --resources-bundle-file needs an active bundle: Config rejects bundle=none AND ignore
-  // (resourcesBundleFile requires an active bundle mode). Front-run that with a clean usage error.
+  // --resources-bundle-file needs an active bundle mode (unlike --bundle-file, inert under ignore).
   if (resourcesBundleFile && (bundle === 'none' || bundle === 'ignore')) usage('Error: --resources-bundle-file requires --bundle=(add|replace|load|frozen)')
   if (bundle === 'load' && lock !== 'frozen' && lock !== 'none' && lock !== 'ignore') usage('Error: --bundle=load is incompatible with --lock=(add|replace)')
   if (lock === 'none' && bundle === 'none') usage('Error: stasis needs a lockfile or a bundle: set --lock or --bundle')
   if (values.mock && bundle === 'load') usage('Error: --mock is for capturing imports while building a bundle; not compatible with --bundle=load')
-  // --fs monkey-patches the fs readers (readFileSync/readdirSync + lstatSync/statSync)
-  // to capture them into the bundle (add|replace) or serve them from it (load); it has
-  // nothing to record into or read from without one of those bundle modes. The mode
-  // argument is required: `sync` patches the sync readers, `async` adds their async
-  // (callback + fs.promises) counterparts on top.
+  // --fs requires a bundle mode (add|replace|load); `sync` patches the sync fs readers,
+  // `async` adds their callback + fs.promises counterparts on top.
   if (values.fs !== undefined && !['sync', 'async'].includes(values.fs)) usage("Error: --fs must be 'sync' or 'async'")
   if (values.fs !== undefined && !['add', 'replace', 'load'].includes(bundle)) usage('Error: --fs requires --bundle=(add|replace|load)')
   const captureFs = values.fs ?? ''
-  // --resources: comma-separated extension/filename allowlist for `--fs` resource captures
-  // (e.g. png,svg,LICENSE). The child's Config validates each entry via parseResourcesOption.
+  // --resources: comma-separated extension/filename allowlist for `--fs` captures.
   const resources = values.resources ?? ''
-  // --brotli-quality: bundle compression quality (0..11; unset = brotli's default 11).
   let brotliQuality
   if (values['brotli-quality'] !== undefined) {
     try {
@@ -116,10 +182,24 @@ if (command === '-v' || command === '--version') {
       usage(`Error: ${cause.message}`)
     }
   }
-  // --child-process: forward forked-child (e.g. Metro transform worker) capture to the root
-  // via per-pid shards. Opt-in -- it stands up a process-coordination channel, off by default.
+  // --import: extra preload module(s) passed through to the spawned node. Node resolves each
+  // against the project cwd; they ride AFTER stasis's own loader import.
+  const imports = values.import ?? []
+  if (imports.some((s) => s === '')) usage('Error: --import requires a module specifier (e.g. --import=./instrument.mjs)')
+  // Not a usage error: plain instrumentation/setup preloads still work under the mock; only ones
+  // that need the denied surfaces (spawning helper processes, network) die, and they do so loudly.
+  if (values.mock && imports.length > 0) {
+    console.warn("[stasis] Warning: --import preloads run under --mock's side-effect denials; a preload that spawns helper processes will fail there")
+  }
+  // --child-process: forward forked-child (e.g. Metro worker) capture to the root via per-pid shards.
   const childProcess = values['child-process'] ? '1' : ''
-  console.warn('[stasis] Running stasis with config:', { lock, scope, bundle, ...(bundleFile && { bundleFile }), ...(resourcesBundleFile && { resourcesBundleFile }), ...(childProcess && { childProcess: true }), ...(values.mock && { mock: true }), ...(values.fs && { fs: values.fs }), ...(resources && { resources }), ...(brotliQuality !== undefined && { brotliQuality }) })
+  // --package-json: auto-include every bundled module's package.json. Only meaningful while WRITING
+  // a bundle (add|replace) -- there's nothing to fold the manifests into otherwise.
+  if (values['package-json'] && bundle !== 'add' && bundle !== 'replace') {
+    usage('Error: --package-json requires --bundle=(add|replace)')
+  }
+  const packageJSON = values['package-json'] ? '1' : ''
+  console.warn('[stasis] Running stasis with config:', { lock, scope, bundle, ...(bundleFile && { bundleFile }), ...(resourcesBundleFile && { resourcesBundleFile }), ...(childProcess && { childProcess: true }), ...(packageJSON && { packageJSON: true }), ...(values.mock && { mock: true }), ...(imports.length > 0 && { import: imports }), ...(values.fs && { fs: values.fs }), ...(resources && { resources }), ...(brotliQuality !== undefined && { brotliQuality }) })
   if (debug) console.warn(`[stasis] Warning: stasis debug mode active`)
   setEnv('EXODUS_STASIS_LOCK', lock)
   setEnv('EXODUS_STASIS_SCOPE', scope)
@@ -128,89 +208,86 @@ if (command === '-v' || command === '--version') {
   setEnv('EXODUS_STASIS_RESOURCES_BUNDLE_FILE', resourcesBundleFile)
   setEnv('EXODUS_STASIS_DEBUG', debug)
   setEnv('EXODUS_STASIS_CHILD_PROCESS', childProcess)
+  setEnv('EXODUS_STASIS_PACKAGE_JSON', packageJSON)
   setEnv('EXODUS_STASIS_FS', captureFs)
   setEnv('EXODUS_STASIS_RESOURCES', resources)
-  // Only set when given, so an ambient EXODUS_STASIS_BROTLI_QUALITY still passes through
-  // to the child (an unconditional setEnv('') would reject it as a conflict).
+  // Only set when given; an unconditional setEnv('') would conflict with an ambient value.
   if (brotliQuality !== undefined) setEnv('EXODUS_STASIS_BROTLI_QUALITY', String(brotliQuality))
-  // --mock: capture imports by running user code with side-effects denied,
-  // fail-closed. Node's permission system blocks fs writes, child processes,
-  // worker threads, native addons (no --allow-addons -- addons would bypass
-  // the whole model), and the inspector. Network and timers have no
-  // --allow-* counterparts, so src/mock.js neutralizes them in JS. We --import
-  // src/loader-mock.js (instead of core's plain loader): it evaluates the core
-  // hooks lib first -- snapshotting stasis's real fs bindings -- then src/mock.js
-  // (whose syncBuiltinESMExports() refresh reaches user-code ESM imports), then
-  // installs the hooks. So the mock runs after stasis's snapshots and before
-  // registration, by static import order and with no env var. Reads stay open
-  // (--allow-fs-read=*) so node_modules resolution works; reads aren't a side
-  // effect. Writes are still scoped at the kernel level as defense in depth (the
-  // JS layer covers user code, --permission covers anything that bypasses JS,
-  // e.g. process.binding or a future leak).
+  // --mock: capture imports by running user code with side-effects denied (fail-closed).
+  // --permission blocks fs writes/child procs/workers/addons/inspector at the kernel level;
+  // src/mock.js neutralizes network + timers in JS (no --allow-* for those). Reads stay open
+  // so node_modules resolution works.
   // Node 24 dropped comma-separated --allow-fs-write; repeat the flag instead.
   const nodeArgs = []
   if (values.mock) {
     const writeAllow = [process.cwd()]
-    // --allow-fs-write paths must already exist on disk; granting a bundle file's own path is not
-    // enough when state.write()'s mkdirSync has to create the parent chain. For each out-of-cwd
-    // bundle target (code and/or split resources), walk up to the nearest existing ancestor and
-    // grant write there -- broader than ideal, but the user explicitly chose these locations.
-    // (Note: the cwd check uses '/' as a separator and is therefore unix-only; that matches the
-    //  rest of the project's path handling.)
+    // --allow-fs-write paths must already exist on disk, so for each out-of-cwd bundle target
+    // walk up to the nearest existing ancestor and grant write there.
     for (const [flag, file] of [['--bundle-file', bundleFile], ['--resources-bundle-file', resourcesBundleFile]]) {
       if (!file || file.startsWith(`${process.cwd()}/`)) continue
       let p = dirname(file)
       while (!existsSync(p) && dirname(p) !== p) p = dirname(p)
-      // Refuse to grant write access to the filesystem root: it would effectively disable the
-      // --permission layer everywhere, and reaching it means none of the path's ancestors exist --
-      // the user almost certainly didn't intend this. Ask them to create a parent.
+      // Refuse write access to the filesystem root -- it would disable the --permission layer everywhere.
       if (p === dirname(p)) {
         usage(`Error: no existing parent directory for ${flag}=${file}; create one first or choose a path under an existing directory`)
       }
-      if (!writeAllow.includes(p)) writeAllow.push(p) // both targets often share a parent dir
+      if (!writeAllow.includes(p)) writeAllow.push(p)
     }
     nodeArgs.push('--permission', '--allow-fs-read=*')
     for (const p of writeAllow) nodeArgs.push(`--allow-fs-write=${p}`)
-    // --permission without --allow-addons removes "node-addons" from resolution
-    // conditions, which would change how packages with conditional exports
-    // resolve and make the captured import map incompatible with a normal
-    // replay. Restore the condition so resolution matches a non-mock run; this
-    // doesn't allow native addons to actually load (--allow-addons still off).
+    // Restore the node-addons resolution condition (dropped by --permission) so the captured
+    // import map matches a non-mock run; native addons still can't load (--allow-addons off).
     nodeArgs.push('--conditions=node-addons')
   }
-  // Non-mock runs use core's loader directly; --mock uses stasis's loader-mock
-  // entry, which composes the mock into the same hooks lib (see comment above).
+  // --mock uses stasis's loader-mock entry (composes the mock before installing the hooks).
   const loaderEntry = values.mock ? '../src/loader-mock.js' : '@exodus/stasis-core/loader'
   nodeArgs.push('--import', import.meta.resolve(loaderEntry))
+  // Passthrough preloads ride after the loader (and after --mock's denials), so they evaluate
+  // under its hooks; their module graphs pass through uncaptured unless the app graph reaches
+  // them -- then they're promoted into the capture (see core hooks.js).
+  for (const specifier of imports) nodeArgs.push('--import', specifier)
   const child = spawn(process.execPath, [...nodeArgs, ...argv], { stdio: 'inherit' })
   const [code, signal] = await once(child, 'close')
   // code is null when the child died from a signal; report 128+signo (shell convention) instead of the implicit 0
   process.exitCode = code ?? 128 + (osConstants.signals[signal] ?? 0)
 } else if (command === 'bundle') {
-  const flags = []
-  const valueFlags = new Set(['--mapping', '--output', '--scope', '--lockfile', '--conditions', '--mainFields', '--platforms', '--brotli-quality', '-o'])
-  while (argv.length > 0 && (argv[0].startsWith('-') || valueFlags.has(flags.at(-1)))) {
-    flags.push(argv.shift())
-  }
   const options = {
     mapping: { type: 'string' },
+    manifests: { type: 'boolean' },
     output: { type: 'string', short: 'o' },
     scope: { type: 'string' },
     lockfile: { type: 'string' },
     conditions: { type: 'string' },
     mainFields: { type: 'string' },
     metro: { type: 'boolean' },
+    'metro-resolver': { type: 'boolean' },
     platforms: { type: 'string', multiple: true },
+    jsx: { type: 'boolean' },
+    flow: { type: 'boolean' },
+    typescript: { type: 'boolean' },
+    tsconfig: { type: 'string' },
+    resources: { type: 'string' },
+    'package-json': { type: 'boolean' },
+    cargo: { type: 'boolean' },
+    'cargo-features': { type: 'string', multiple: true },
+    'cargo-no-default-features': { type: 'boolean' },
+    'cargo-all-features': { type: 'boolean' },
+    'cargo-target': { type: 'string' },
+    'cargo-manifests': { type: 'boolean' },
     'brotli-quality': { type: 'string' },
+    add: { type: 'boolean' },
   }
-  let values
-  try {
-    ({ values } = parseArgs({ args: flags, options }))
-  } catch (cause) {
-    usage(`Error: ${cause.message}`)
-  }
+  const values = parseLeadingOptions(argv, options, {
+    valueFlags: ['--mapping', '--output', '--scope', '--lockfile', '--conditions', '--mainFields', '--platforms', '--resources', '--tsconfig', '--cargo-features', '--cargo-target', '--brotli-quality', '-o'],
+    onError: usage,
+  })
   if (argv.length === 0) usage('Nothing to bundle: no entry file given')
-  const allSol = argv.every((f) => f.endsWith('.sol'))
+  // A directory entry stands for the .sol files under it (Solidity only); an extensionless path
+  // that doesn't exist is a missing one (skipped with a warning).
+  const { directoryEntryError, isSolidityEntry } = await import('../src/cmd/bundle.js')
+  const dirError = directoryEntryError(argv)
+  if (dirError !== null) usage(`Error: ${dirError}`)
+  const allSol = argv.every((f) => isSolidityEntry(f))
   const allPhp = argv.every((f) => f.endsWith('.php'))
   const allJs = argv.every((f) => /\.(?:js|cjs|mjs|ts|cts|mts)$/u.test(f))
   const allBash = argv.every((f) => /\.(?:sh|bash)$/u.test(f))
@@ -219,21 +296,46 @@ if (command === '-v' || command === '--version') {
     usage('Error: bundle entries must all be .sol, all be .php, all be .js/.cjs/.mjs/.ts/.cts/.mts, all be .sh/.bash, or all be .rs')
   }
   if (values.mapping && !allSol) usage('Error: --mapping is only valid for .sol bundles')
+  // --manifests: carry the Solidity build's description files (foundry.toml, remappings.txt, ...).
+  const manifests = Boolean(values.manifests)
+  if (manifests && !allSol) usage('Error: --manifests is only valid for .sol bundles')
+  // --cargo: take the Rust feature/dependency resolution from `cargo metadata` (runs cargo; opt-in).
+  const cargo = Boolean(values.cargo)
+  if (cargo && !allRust) usage('Error: --cargo is only valid for Rust bundles')
+  // --cargo-features / --cargo-no-default-features / --cargo-all-features: cargo's own feature flags
+  // for the entries' packages (`pkg/feat` targets one, or a dependency). --cargo-features is
+  // repeatable and/or comma-separated; parseFeatureList is the one splitter (the resolver reuses it).
+  const { parseFeatureList } = await import('../src/loaders/cargo.js')
+  const cargoFeatures = parseFeatureList(values['cargo-features'] ?? [])
+  if (values['cargo-features'] !== undefined && cargoFeatures.length === 0) {
+    usage('Error: --cargo-features must list at least one feature (e.g. --cargo-features=serde,app/tls)')
+  }
+  const cargoNoDefaultFeatures = Boolean(values['cargo-no-default-features'])
+  const cargoAllFeatures = Boolean(values['cargo-all-features'])
+  // --cargo-target=<triple|host>: the build's target, whose cfgs (from `rustc --print cfg`) decide
+  // `#[cfg(unix)]`-style code. A triple is letters, digits, `-`, `_` and `.` (`x86_64-unknown-linux-gnu`).
+  const cargoTarget = values['cargo-target'] ?? null
+  if (cargoTarget !== null && !/^[\w.-]+$/u.test(cargoTarget)) {
+    usage('Error: --cargo-target must be a target triple or "host" (e.g. --cargo-target=aarch64-apple-darwin)')
+  }
+  // --cargo-manifests: carry each bundled package's Cargo.toml and build script, the workspace
+  // Cargo.toml, Cargo.lock and .cargo/config.toml too (the Rust counterpart of --package-json).
+  const cargoManifests = Boolean(values['cargo-manifests'])
+  if (!allRust) {
+    const given = { 'cargo-features': cargoFeatures.length > 0, 'cargo-no-default-features': cargoNoDefaultFeatures, 'cargo-all-features': cargoAllFeatures, 'cargo-target': cargoTarget !== null, 'cargo-manifests': cargoManifests }
+    for (const [flag, on] of Object.entries(given)) if (on) usage(`Error: --${flag} is only valid for Rust bundles`)
+  }
   if (values.scope && !allJs) usage('Error: --scope is only valid for JS bundles')
   if (values.scope && !['node_modules', 'full'].includes(values.scope)) {
     usage('Error: --scope must be node_modules or full')
   }
   if (values.lockfile && !allJs) usage('Error: --lockfile is only valid for JS bundles')
-  // --scope selects a bundle subset; the field resolver (--mainFields/--metro) always
-  // emits a full-scope bundle, so the two together would silently ignore --scope.
+  // --mainFields/--metro always emit a full-scope bundle, so they'd silently ignore --scope.
   if (values.scope !== undefined && (values.mainFields !== undefined || values.metro)) {
     usage('Error: --scope is not supported with --mainFields or --metro')
   }
-  // --conditions: comma-separated extra `exports`/`imports` resolution conditions
-  // (e.g. react-native,browser) merged on top of the conditions Node always asserts.
-  // They steer which branch of a package's conditional `exports` the static scan
-  // follows. NOTE: conditions alone do not honour legacy package `mainFields` or
-  // platform-specific file suffixes -- see --mainFields.
+  // --conditions: extra exports/imports resolution conditions merged onto Node's defaults;
+  // they don't honour legacy `mainFields` or platform suffixes (see --mainFields).
   if (values.conditions !== undefined && !allJs) usage('Error: --conditions is only valid for JS bundles')
   const conditions = values.conditions === undefined
     ? []
@@ -241,9 +343,17 @@ if (command === '-v' || command === '--version') {
   if (values.conditions !== undefined && conditions.length === 0) {
     usage('Error: --conditions must list at least one condition name (e.g. --conditions=react-native,browser)')
   }
-  // --mainFields: comma-separated legacy package entry fields (e.g.
-  // react-native,browser,main). Drives the legacy-field resolver for non-`exports`
-  // packages -- the entry it picks plus the browser-field-spec object redirection.
+  // --flow: strip Flow type syntax (via the optional flow-remove-types dep) before parsing; JS-only.
+  if (values.flow && !allJs) usage('Error: --flow is only valid for JS bundles')
+  const flow = Boolean(values.flow)
+  // --typescript: resolve like tsc -- a specifier naming a missing JS output (./x.js, .mjs, .cjs,
+  // extensionless) lands on its on-disk TS source (./x.ts, .mts, .cts); an existing .js always wins.
+  if (values.typescript && !allJs) usage('Error: --typescript is only valid for JS bundles')
+  const typescript = Boolean(values.typescript)
+  // --tsconfig: the config whose compilerOptions.paths aliases --typescript honours (default:
+  // the project root's tsconfig.json when present). Meaningless without --typescript.
+  if (values.tsconfig !== undefined && !typescript) usage('Error: --tsconfig is only valid with --typescript')
+  // --mainFields: legacy package entry fields (e.g. react-native,browser,main) for the non-exports resolver.
   if (values.mainFields !== undefined && !allJs) usage('Error: --mainFields is only valid for JS bundles')
   const mainFields = values.mainFields === undefined
     ? undefined
@@ -251,19 +361,42 @@ if (command === '-v' || command === '--version') {
   if (values.mainFields !== undefined && mainFields.length === 0) {
     usage('Error: --mainFields must list at least one field (e.g. --mainFields=react-native,browser,main)')
   }
-  // --metro: resolve like Metro/React Native -- it sets its own conditions
-  // (react-native, +browser for web) and mainFields, and resolves platform suffixes
-  // (.ios/.android/.native) for each --platforms target, bundling all of them at once.
-  // --platforms is repeatable and/or comma-separated; the values union.
+  // --metro: resolve like Metro/RN (its own conditions + mainFields, platform suffixes per
+  // --platforms target). --platforms is repeatable and/or comma-separated; the values union.
   const metro = Boolean(values.metro)
+  // --metro-resolver: resolve through the project's own metro-resolver instead of the built-in
+  // approximation. Only meaningful alongside --metro (enforced below and in classifyEntries).
+  const metroResolver = Boolean(values['metro-resolver'])
   const platforms = [...new Set((values.platforms ?? []).flatMap((p) => p.split(',')).map((s) => s.trim()).filter(Boolean))]
-  // A platform name becomes a bundle/lockfile edge key, which the parsers reject if it
-  // contains '/'; '*' is the reserved private placeholder. Reject both here so we never
-  // emit a bundle the readers can't parse (the divergent-edge case is data-dependent).
+  // A platform name becomes an edge key: reject '/' (parsers reject it) and '*' (reserved placeholder).
   for (const p of platforms) {
     if (p === '*' || p.includes('/')) usage(`Error: invalid --platforms value '${p}' (a platform name can't contain '/' or be '*')`)
   }
   if ((metro || platforms.length > 0) && !allJs) usage('Error: --metro is only valid for JS bundles')
+  // --jsx: parse React Native's JSX-in-.js source in the static scanner (off by default; oxc,
+  // like tsc, only auto-enables JSX for .jsx/.tsx). Orthogonal to the resolver, so it pairs with
+  // plain/--mainFields/--metro alike -- JS-only, since no other entry language is scanned.
+  const jsx = Boolean(values.jsx)
+  if (jsx && !allJs) usage('Error: --jsx is only valid for JS bundles')
+  // --package-json: fold each bundled module's package.json into the bundle. JS-only (only JS
+  // modules carry an npm package.json; the sol/php/bash/rust bucketizers have no such manifest).
+  const packageJSON = Boolean(values['package-json'])
+  if (packageJSON && !allJs) usage('Error: --package-json is only valid for JS bundles')
+  // --resources: comma-separated extension/filename allowlist for assets reached through the graph
+  // (e.g. --resources=png,svg). They're carried as resources instead of failing "can't carry" --
+  // for graphs that aren't fully loadable in JS (Metro consumes such assets). JS-only.
+  if (values.resources !== undefined && !allJs) usage('Error: --resources is only valid for JS bundles')
+  const resources = values.resources === undefined
+    ? []
+    : values.resources.split(',').map((s) => s.trim()).filter(Boolean)
+  if (values.resources !== undefined && resources.length === 0) {
+    usage('Error: --resources must list at least one extension or filename (e.g. --resources=png,svg)')
+  }
+  try {
+    parseResourcesOption('--resources', resources) // validate early for a clean usage error (code exts / bad chars rejected)
+  } catch (cause) {
+    usage(`Error: ${cause.message}`)
+  }
   if (metro) {
     if (conditions.length > 0) usage("Error: --conditions can't be combined with --metro (it sets its own conditions)")
     if (mainFields !== undefined) usage("Error: --mainFields can't be combined with --metro (it sets its own mainFields)")
@@ -271,7 +404,10 @@ if (command === '-v' || command === '--version') {
   } else if (platforms.length > 0) {
     usage('Error: --platforms is only valid with --metro')
   }
-  // --brotli-quality: output-encoding knob, valid for every entry language (no allJs gate).
+  if (metroResolver && !metro) usage('Error: --metro-resolver is only valid with --metro')
+  // metro-resolver can't substitute .js -> .ts, so --typescript would silently not apply -- reject it.
+  if (typescript && metroResolver) usage("Error: --typescript is not supported with --metro-resolver (the project's metro-resolver doesn't substitute .js -> .ts)")
+  // --brotli-quality: valid for every entry language (no allJs gate).
   let brotliQuality
   if (values['brotli-quality'] !== undefined) {
     try {
@@ -280,69 +416,157 @@ if (command === '-v' || command === '--version') {
       usage(`Error: ${cause.message}`)
     }
   }
+  // --add merges into the existing bundle at --output, so it can't target write-only stdout.
+  const add = Boolean(values.add)
+  if (add && values.output === '-') usage('Error: --add cannot be combined with --output=-')
   const { bundleCommand } = await import('../src/cmd/bundle.js')
   await bundleCommand({
     cwd: process.cwd(),
     entries: argv,
     mappingFile: values.mapping,
+    manifests,
     output: values.output,
     scope: values.scope,
     lockfile: values.lockfile,
     conditions,
     mainFields,
     metro,
+    metroResolver,
     platforms,
+    jsx,
+    flow,
+    typescript,
+    tsconfig: values.tsconfig,
+    resources,
+    packageJSON,
+    cargo,
+    cargoFeatures,
+    cargoNoDefaultFeatures,
+    cargoAllFeatures,
+    cargoTarget,
+    cargoManifests,
     brotliQuality,
+    add,
   })
-} else if (command === 'build') {
-  const flags = []
-  const valueFlags = new Set(['--output', '-o', '--format', '--platform', '--define', '--external', '--loader'])
-  while (argv.length > 0 && (argv[0].startsWith('-') || valueFlags.has(flags.at(-1)))) {
-    flags.push(argv.shift())
+} else if (command === 'github-bundle') {
+  const values = parseLeadingOptions(argv, {
+    github: { type: 'string' },
+    sha: { type: 'string' },
+    tag: { type: 'string' },
+    directory: { type: 'string' },
+    'package-manager': { type: 'string' },
+    'package-manager-version': { type: 'string' },
+    mapping: { type: 'string' },
+    manifests: { type: 'boolean' },
+    output: { type: 'string', short: 'o' },
+    scope: { type: 'string' },
+    lockfile: { type: 'string' },
+    conditions: { type: 'string' },
+    mainFields: { type: 'string' },
+    metro: { type: 'boolean' },
+    platforms: { type: 'string', multiple: true },
+    jsx: { type: 'boolean' },
+    flow: { type: 'boolean' },
+    typescript: { type: 'boolean' },
+    tsconfig: { type: 'string' },
+    resources: { type: 'string' },
+    'package-json': { type: 'boolean' },
+    'brotli-quality': { type: 'string' },
+  }, {
+    valueFlags: ['--github', '--sha', '--tag', '--directory', '--package-manager', '--package-manager-version', '--mapping', '--output', '--scope', '--lockfile', '--conditions', '--mainFields', '--platforms', '--tsconfig', '--resources', '--brotli-quality', '-o'],
+    onError: usage,
+  })
+  if (values.github === undefined) usage('Error: github-bundle requires --github=owner/name, the repo to bundle')
+  if (values.sha !== undefined && values.tag !== undefined) usage('Error: github-bundle takes --sha or --tag, not both')
+  // Whether each option applies to the entries is buildGitHubBundle's to say.
+  const list = (value) => [value ?? []].flat().flatMap((v) => v.split(',')).map((s) => s.trim()).filter(Boolean)
+  let brotliQuality
+  if (values['brotli-quality'] !== undefined) {
+    try {
+      brotliQuality = parseBrotliQuality('--brotli-quality', values['brotli-quality'])
+    } catch (cause) {
+      usage(`Error: ${cause.message}`)
+    }
   }
+  // Tarballs, zips and GitHub trees are cached where `stasis audit` caches.
+  const { setCacheDir } = await import('../src/vfs-bundle.js')
+  setCacheDir(userCacheDir())
+  const { githubBundleCommand } = await import('../src/cmd/github-bundle.js')
+  await githubBundleCommand({
+    github: values.github,
+    sha: values.sha,
+    tag: values.tag,
+    directory: values.directory,
+    packageManager: values['package-manager'],
+    packageManagerVersion: values['package-manager-version'],
+    entries: argv.length === 0 ? undefined : argv,
+    mappingFile: values.mapping,
+    manifests: Boolean(values.manifests),
+    output: values.output,
+    lockfile: values.lockfile,
+    scope: values.scope,
+    conditions: list(values.conditions),
+    mainFields: values.mainFields === undefined ? undefined : list(values.mainFields),
+    metro: Boolean(values.metro),
+    platforms: list(values.platforms),
+    jsx: Boolean(values.jsx),
+    flow: Boolean(values.flow),
+    typescript: Boolean(values.typescript),
+    tsconfig: values.tsconfig,
+    resources: list(values.resources),
+    packageJSON: Boolean(values['package-json']),
+    brotliQuality,
+  })
+} else if (command === 'add') {
+  // add packs the listed files (no resolver), taking split targets + resource allowlist from
+  // stasis.config.json; it takes no flags.
+  if (argv.length === 0) usage('Nothing to add: no file given')
+  if (argv.some((a) => a.startsWith('-'))) usage('Error: add takes no options; its targets and resource allowlist come from stasis.config.json')
+  const { addCommand } = await import('@exodus/stasis-core/add')
+  // Let addCommand's runtime errors propagate as-is; wrapping in usage() would bury the cause.
+  addCommand({ cwd: process.cwd(), entries: argv, logLabel: 'stasis' })
+} else if (command === 'build') {
   const options = {
     output: { type: 'string', short: 'o' },
     format: { type: 'string' },
     platform: { type: 'string' },
+    babel: { type: 'boolean' },
     minify: { type: 'boolean' },
     sourcemap: { type: 'boolean' },
-    // Repeatable esbuild passthroughs: --define=K=V (one substitution each),
-    // --external=PATTERN (one external each), and --loader=.ext:name (one extension
-    // loader override each). Each collects into an array.
+    // Repeatable esbuild passthroughs (--define=K=V, --external=PATTERN, --loader=.ext:name).
     define: { type: 'string', multiple: true },
     external: { type: 'string', multiple: true },
     loader: { type: 'string', multiple: true },
   }
-  let values
-  try {
-    ({ values } = parseArgs({ args: flags, options }))
-  } catch (cause) {
-    usage(`Error: ${cause.message}`)
-  }
+  const values = parseLeadingOptions(argv, options, {
+    valueFlags: ['--output', '-o', '--format', '--platform', '--define', '--external', '--loader'],
+    onError: usage,
+  })
   if (argv.length === 0) usage('Nothing to build: no bundle or lockfile given')
   if (argv.length > 2) usage('Error: build takes a bundle or lockfile and an optional entry point')
   // esbuild output knobs; the import graph itself is fixed by the artifact, not these.
   if (values.format !== undefined && !['esm', 'cjs', 'iife'].includes(values.format)) {
     usage('Error: --format must be esm, cjs, or iife')
   }
-  if (values.platform !== undefined && !['node', 'browser', 'neutral'].includes(values.platform)) {
-    usage('Error: --platform must be node, browser, or neutral')
+  if (values.platform !== undefined && !['node', 'browser', 'neutral', 'hermes'].includes(values.platform)) {
+    usage('Error: --platform must be node, browser, neutral, or hermes')
+  }
+  // Hermes has no import/export; --format defaults to iife under --platform=hermes (see buildCommand).
+  if (values.platform === 'hermes' && values.format === 'esm') {
+    usage('Error: --platform=hermes cannot emit ESM; use --format=iife (the hermes default) or cjs')
   }
   if (!values.output) usage('Error: --output is required (a .js/.cjs/.mjs file, or a directory)')
-  // `-` is the stdout sentinel for `bundle`/`sbom`, but `build` writes via esbuild and can't
-  // stream; without this it would silently create a directory literally named `-`.
+  // build can't stream to stdout; without this, --output=- would create a dir literally named `-`.
   if (values.output === '-') usage('Error: stasis build cannot stream to stdout; --output must be a .js/.cjs/.mjs file or a directory')
-  // --define=KEY=VALUE -> esbuild's define map. The value is forwarded to esbuild verbatim,
-  // so it must be valid JS the same way esbuild's CLI requires (a JSON literal, an
-  // identifier, ...): e.g. --define=process.env.NODE_ENV='"production"' or --define=DEBUG=false.
+  // --define=KEY=VALUE -> esbuild define map; VALUE is forwarded verbatim and must be valid JS
+  // (a JSON literal or an identifier), e.g. --define=DEBUG=false.
   const define = {}
   for (const entry of values.define ?? []) {
     const eq = entry.indexOf('=')
     if (eq <= 0) usage(`Error: --define must be KEY=VALUE (got '${entry}')`)
     define[entry.slice(0, eq)] = entry.slice(eq + 1)
   }
-  // --loader=.ext:NAME -> esbuild loader override for that extension, e.g.
-  // --loader=.js:jsx so a .js file carrying JSX (the React Native convention) parses.
+  // --loader=.ext:NAME -> esbuild loader override for that extension (e.g. --loader=.js:jsx).
   const loader = {}
   for (const entry of values.loader ?? []) {
     const colon = entry.indexOf(':')
@@ -357,6 +581,7 @@ if (command === '-v' || command === '--version') {
     output: values.output,
     format: values.format,
     platform: values.platform,
+    babel: Boolean(values.babel),
     minify: values.minify,
     sourcemap: values.sourcemap,
     define,
@@ -364,48 +589,28 @@ if (command === '-v' || command === '--version') {
     loader,
   })
 } else if (command === 'extract') {
-  const flags = []
-  const valueFlags = new Set(['--output', '-o'])
-  while (argv.length > 0 && (argv[0].startsWith('-') || valueFlags.has(flags.at(-1)))) {
-    flags.push(argv.shift())
-  }
   const options = {
     output: { type: 'string', short: 'o' },
   }
-  let values
-  try {
-    ({ values } = parseArgs({ args: flags, options }))
-  } catch (cause) {
-    usage(`Error: ${cause.message}`)
-  }
+  const values = parseLeadingOptions(argv, options, { valueFlags: ['--output', '-o'], onError: usage })
   if (argv.length === 0) usage('Nothing to extract: no bundle file given')
   if (argv.length > 1) usage('Error: extract takes exactly one bundle file')
-  const { extractCommand } = await import('../src/cmd/extract.js')
-  extractCommand({ cwd: process.cwd(), bundleFile: argv[0], output: values.output })
+  const { extractCommand } = await import('@exodus/stasis-core/extract')
+  extractCommand({ cwd: process.cwd(), bundleFile: argv[0], output: values.output, logLabel: 'stasis' })
 } else if (command === 'diff') {
-  const flags = []
-  while (argv.length > 0 && argv[0].startsWith('-')) flags.push(argv.shift())
   const options = {
     stat: { type: 'boolean' },
     imports: { type: 'boolean' },
   }
-  let values
-  try {
-    ({ values } = parseArgs({ args: flags, options }))
-  } catch (cause) {
-    usage(`Error: ${cause.message}`)
-  }
-  // --stat is required until full text diffs land: it reports what changed
-  // (modules/files), not the differing content. Reserving bare `stasis diff`
-  // keeps the door open for a future content-level diff without a breaking flag.
+  const values = parseLeadingOptions(argv, options, { onError: usage })
+  // --stat is required for now (it reports what changed, not the content); bare `stasis diff`
+  // is reserved for a future content-level diff.
   if (!values.stat) usage('Error: stasis diff currently requires --stat')
   if (argv.length !== 2) usage('Error: stasis diff takes exactly two files (lockfile or bundle)')
-  // --imports additionally diffs the resolution graphs (which import edges were
-  // added/removed/redirected); off by default since the edge list is verbose.
+  // --imports also diffs the resolution graphs (added/removed/redirected edges); off by default (verbose).
   const { diffCommand } = await import('../src/cmd/diff.js')
   const { differences } = diffCommand({ cwd: process.cwd(), left: argv[0], right: argv[1], stat: true, imports: values.imports })
-  // Exit non-zero when the artifacts differ, so the command composes in CI
-  // (e.g. fail a build when a bundle drifts from its lockfile).
+  // Exit non-zero when the artifacts differ, so it composes in CI.
   process.exitCode = differences ? 1 : 0
 } else if (command === 'prune') {
   if (argv.length > 1) usage('Error: prune takes at most one path argument')
@@ -414,28 +619,28 @@ if (command === '-v' || command === '--version') {
   const { removed, validated } = prune({ root })
   console.warn(`[stasis] prune: validated ${validated.length} file(s), removed ${removed.length} file(s)`)
 } else if (command === 'audit') {
+  const values = parseLeadingOptions(argv, { why: { type: 'boolean' }, 'why-deep': { type: 'boolean' }, 'why-full': { type: 'boolean' }, reason: { type: 'string' }, 'repo-advisories': { type: 'boolean' } }, { valueFlags: ['--reason'], onError: usage })
   if (argv.length === 0) usage('Nothing to audit: no path to file given')
+  const repoAdvisories = Boolean(values['repo-advisories'])
+  if (repoAdvisories && !process.env.GITHUB_TOKEN) usage('Error: --repo-advisories requires a GitHub token in GITHUB_TOKEN')
+  // A Soldeer package's and a GitHub repo's advisories are their repository's, asked of GitHub with
+  // GITHUB_TOKEN where it is set; the client asks nothing for any other package by itself.
+  const github = (await import('@preventive/upstream/github.js')).createClient({ token: process.env.GITHUB_TOKEN || null })
+  // Upstream caches what it looks up (a package's GitHub repo, a month each) only where told to, and
+  // answers from it without asking: a per-user directory, never one shared with less trusted jobs.
+  const { setCacheDir } = await import('@preventive/upstream/npm.js')
+  setCacheDir(userCacheDir())
   const { audit, printAuditReport } = await import('../src/audit.js')
   const files = argv.map((f) => resolve(f))
-  const report = await audit(files)
+  const report = await audit(files, { why: Boolean(values.why), whyDeep: Boolean(values['why-deep']), whyFull: Boolean(values['why-full']), reason: values.reason, repoAdvisories, github })
   printAuditReport(report)
   process.exitCode = report.rows.length === 0 ? 0 : 1
 } else if (command === 'sbom') {
-  const flags = []
-  const valueFlags = new Set(['--format', '--output', '-o'])
-  while (argv.length > 0 && (argv[0].startsWith('-') || valueFlags.has(flags.at(-1)))) {
-    flags.push(argv.shift())
-  }
   const options = {
     format: { type: 'string' },
     output: { type: 'string', short: 'o' },
   }
-  let values
-  try {
-    ({ values } = parseArgs({ args: flags, options }))
-  } catch (cause) {
-    usage(`Error: ${cause.message}`)
-  }
+  const values = parseLeadingOptions(argv, options, { valueFlags: ['--format', '--output', '-o'], onError: usage })
   if (!values.format) usage('Error: stasis sbom requires --format=(spdx|cyclonedx)')
   if (!['spdx', 'cyclonedx'].includes(values.format)) usage('Error: --format must be spdx or cyclonedx')
   if (argv.length === 0) usage('Nothing to export: no lockfile or bundle given')