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

package/README.md

@@ -2,6 +2,11 @@
 
 *Analyzeable source code bundles with resolutions + fine-grained lockfiles.*
 
+[![Node.js](https://img.shields.io/badge/Node.js-338750?style=for-the-badge&logo=Node.js&logoColor=FFF)](https://nodejs.org/)
+[![esbuild](https://img.shields.io/badge/esbuild-191919?style=for-the-badge&logo=esbuild)](https://esbuild.github.io/)
+[![metro](https://img.shields.io/badge/metro-FFF?style=for-the-badge&logo=Metro&logoColor=Ef4242)](https://metrobundler.dev/)
+[![webpack](https://img.shields.io/badge/WebPack-2B3A42?style=for-the-badge&logo=WebPack)](https://webpack.js.org/)
+
 Both lockfiles and bundles only include what is actually _used_.\
 Generally about 10x smaller than production-focused `node_modules` install.
 
@@ -53,9 +58,14 @@ _Lockfiles (npm/pnpm/etc) not mentioned: they are like the "tarball" column, but
 | `stasis run --lock=add --child-process app.js` | also attest modules loaded in forked child processes (e.g. Metro transform workers) |
 | `stasis run --bundle=add --fs=sync app.js` | build a bundle that also captures sync `fs.readFileSync`/`readdirSync` reads |
 | `stasis bundle src/index.js` | build a bundle statically, without executing it |
+| `stasis bundle --add src/worker.js` | merge more entries (and their import graph) into an existing `stasis.code.br` instead of replacing it |
+| `stasis add a.js icon.svg` | add the listed files to the project's bundles (config-driven), with no dependency resolution |
+| `stasis add src assets` | same, expanding each directory to every file under it, minus an auto-excluded set unless explicitly named |
 | `stasis bundle --conditions=react-native,browser app.js` | statically bundle, asserting extra `exports`/`imports` resolution conditions |
 | `stasis bundle --mainFields=react-native,browser,main app.js` | statically bundle, honoring legacy package `mainFields` (incl. browser-field object redirection) |
-| `stasis bundle --metro --platforms=ios,android app.js` | statically bundle the way Metro resolves: RN conditions + mainFields + `.ios`/`.android`/`.native` suffixes, all platforms at once |
+| `stasis bundle --metro --platforms=ios,android app.js` | statically bundle the way Metro resolves: RN conditions + mainFields + `.ios`/`.android`/`.native` suffixes, all platforms at once, plus each bundled native dependency's `ios/`/`android/` sources + podspec |
+| `stasis bundle --metro --metro-resolver --platforms=ios,android app.js` | same, but resolve through the project's own `metro-resolver` (byte-for-byte Metro fidelity) instead of the built-in approximation; requires `metro-resolver` installed (it ships with `react-native`/`metro`) |
+| `stasis bundle --flow app.js` | statically bundle Flow-typed sources: when oxc can't parse a `.js`/`.cjs`/`.mjs` file, strip its Flow syntax and retry so the import graph resolves (needs the optional `flow-remove-types` dependency; the stored source stays the original bytes). Combines with `--jsx`/`--conditions`/`--mainFields`/`--metro` |
 | `stasis build --output=out.js app.stasis.code.br [entry]` | rebuild a runnable JS bundle with esbuild, following the bundle's recorded import graph exactly (entry optional when the bundle has one) |
 | `stasis build --output=out.js stasis.lock.json [entry]` | same, reading + verifying sources from disk against the lockfile |
 | `stasis extract app.stasis.code.br` | unpack a bundle back to sources + a `stasis.lock.json` |
@@ -63,12 +73,16 @@ _Lockfiles (npm/pnpm/etc) not mentioned: they are like the "tarball" column, but
 | `stasis prune` | trim `node_modules` to the lockfile, verifying the rest |
 | `stasis audit stasis.lock.json` | report npm advisories for a lockfile's dependencies |
 | `stasis audit app.stasis.code.br` | report npm advisories for a bundle's dependencies |
+| `stasis audit --why app.stasis.code.br` | same, with the cross-module import paths that pull each flagged package in (`run: a -> b -> c`), prefixed by the consumer that imports each chain at the top level; a chain is skipped when its full tail is already listed as its own chain |
+| `stasis audit --why-deep app.stasis.code.br` | like `--why`, but keep those longer chains too (every path, shared tails collapsed to `a -> b -> ... -> d`) |
+| `stasis audit --why-full app.stasis.code.br` | like `--why`, but spell every chain out with no `...` collapse (combine with `--why-deep` for the complete raw listing) |
+| `stasis audit --reason=run app.stasis.code.br` | show only advisories related to one consumer (`run`); with `--why`, keep only that consumer's chains |
 | `stasis sbom --format=spdx stasis.lock.json` | export an SPDX SBOM for a lockfile or bundle |
 | `stasis sbom --format=cyclonedx app.stasis.code.br` | export a CycloneDX SBOM for a lockfile or bundle |
 
 ## Runtime
 
-The zero-dependency [`@exodus/stasis-core`](../stasis-core) CLI provides `run` and `prune` commands only; the bundler plugins live in [`@exodus/stasis-plugins`](../stasis-plugins).
+The zero-dependency [`@exodus/stasis-core`](../stasis-core) CLI provides `run`, `prune`, and `add` commands only; the bundler plugins live in [`@exodus/stasis-plugins`](../stasis-plugins).
 
 ## License
 

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 { existsSync, realpathSync } from 'node:fs'
 import { 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,42 @@ 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] [--fs=(sync|async)] [--resources=ext,ext] [--brotli-quality=0..11] path/to/file.js ...
+ stasis bundle [--mapping=path/to/remappings(.txt|.toml)] [--add] [--output=(path|-)] path/to/file.sol ...
+ stasis bundle [--add] [--output=(path|-)] path/to/file.php ...
+ stasis bundle [--scope=(node_modules|full)] [--conditions=cond1,cond2] [--mainFields=field1,field2] [--jsx] [--flow] [--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] [--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 [--add] [--output=(path|-)] path/to/file.rs ...
+ (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);
+  --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 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] path/to/file ...
+ (--why lists, per advisory, the cross-module import paths that pull the 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)
  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)
 }
@@ -53,12 +67,6 @@ 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 +75,16 @@ if (command === '-v' || command === '--version') {
     debug: { type: 'boolean' },
     dependencies: { type: 'boolean' },
     'child-process': { type: 'boolean' },
+    'package-json': { type: 'boolean' },
     mock: { type: 'boolean' },
     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', '--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 +95,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 +115,15 @@ 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.
+  // --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 }), ...(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,58 +132,38 @@ 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))
   const child = spawn(process.execPath, [...nodeArgs, ...argv], { stdio: 'inherit' })
@@ -187,11 +171,6 @@ if (command === '-v' || command === '--version') {
   // 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' },
     output: { type: 'string', short: 'o' },
@@ -200,15 +179,19 @@ if (command === '-v' || command === '--version') {
     conditions: { type: 'string' },
     mainFields: { type: 'string' },
     metro: { type: 'boolean' },
+    'metro-resolver': { type: 'boolean' },
     platforms: { type: 'string', multiple: true },
+    jsx: { type: 'boolean' },
+    flow: { type: 'boolean' },
+    resources: { type: 'string' },
+    'package-json': { 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', '--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'))
   const allPhp = argv.every((f) => f.endsWith('.php'))
@@ -224,16 +207,12 @@ if (command === '-v' || command === '--version') {
     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 +220,10 @@ 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)
+  // --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 +231,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 +274,8 @@ 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')
+  // --brotli-quality: valid for every entry language (no allJs gate).
   let brotliQuality
   if (values['brotli-quality'] !== undefined) {
     try {
@@ -280,6 +284,9 @@ 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(),
@@ -291,58 +298,65 @@ if (command === '-v' || command === '--version') {
     conditions,
     mainFields,
     metro,
+    metroResolver,
     platforms,
+    jsx,
+    flow,
+    resources,
+    packageJSON,
     brotliQuality,
+    add,
   })
+} 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 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())
-  }
   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 +371,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 +379,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 +409,19 @@ 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' } }, { valueFlags: ['--reason'], onError: usage })
   if (argv.length === 0) usage('Nothing to audit: no path to file given')
   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 })
   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')