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

package/README.md

@@ -5,6 +5,7 @@
 [![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/)
+[![rollup](https://img.shields.io/badge/Rollup-EC4A3F?style=for-the-badge&logo=rollupdotjs&logoColor=FFF)](https://rollupjs.org/)
 [![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_.\
@@ -57,6 +58,7 @@ _Lockfiles (npm/pnpm/etc) not mentioned: they are like the "tarball" column, but
 | `stasis run --lock=add --bundle=add --mock app.js` | build without the app's side effects (network, fs writes) |
 | `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 run --lock=add --import=./instrument.mjs app.js` | forward extra preload modules (repeatable) to the node process running the entry: a preload's own module graph is runner infrastructure like stasis's loader itself — evaluated, but not captured. Modules the app graph *also* reaches (or that execute through a preload-transplanted `require()` pipeline) are still attested like any other app code, so frozen replays and `--bundle=load` stay fail-closed |
 | `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 |
@@ -66,17 +68,21 @@ _Lockfiles (npm/pnpm/etc) not mentioned: they are like the "tarball" column, but
 | `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 bundle --typescript src/index.ts` | statically bundle TS sources that import by output name, the way tsc resolves: a `./x.js` (or `.mjs`/`.cjs`) specifier with no such file on disk lands on its on-disk `./x.ts` (`.mts`/`.cts`) source, and an extensionless `./x` probes `./x.ts` and `./x/index.ts`; the same substitution applies to package `main`/`exports`/`imports` targets and bare subpaths, and an existing `.js` always wins over its `.ts` twin. Combines with `--jsx` (also maps to `.tsx`)/`--conditions`/`--mainFields`/`--metro` (not `--metro-resolver`, which can't substitute) |
+| `stasis bundle --typescript --tsconfig=tsconfig.build.json src/index.ts` | same, honoring tsconfig `compilerOptions.paths` aliases (e.g. `"@/*": ["./src/*"]`, resolved against `baseUrl`, `extends` followed) for bare specifiers nothing else resolves; without `--tsconfig`, the project root's tsconfig.json applies when present |
+| `stasis github-bundle --github=owner/name [--sha=<commit>] [--tag=<name>] [--directory=path] [--package-manager=pnpm] [src/index.js]` | statically bundle a GitHub repo at a commit, or the one `--tag` names (the 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 (`pnpm`, `yarn1`, `npm`, or `soldeer` for `.sol` entries; without `--package-manager`, the one whose lockfile installs the directory, where only one's does), with nothing installed and no package script run; where no entries are given, they are the JS files the directory's `package.json` names (`main`, `exports`, `bin`), resolved as the build resolves (`--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; written 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); takes `stasis bundle`'s options for the entries and `--lockfile` (as a library: `buildGitHubBundle` in `@exodus/stasis/vfs-bundle`, and `suggestedEntries` for the entries it would take, of a GitHub repo or a Vfs) |
 | `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` |
 | `stasis diff --stat a.lock.json b.stasis.code.br` | summarize module/file differences between two lockfiles/bundles |
 | `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 app.stasis.code.br` | report advisories for a bundle's dependencies: 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 |
 | `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 |
+| `GITHUB_TOKEN=... stasis audit --repo-advisories stasis.lock.json` | also ask each dependency's GitHub repository for the advisories its maintainers published there, which npm's database has only once GitHub reviews them; needs a GitHub token in `GITHUB_TOKEN`. Each package's repository is cached for a month in the user cache directory (`$XDG_CACHE_HOME/stasis`, `~/.cache/stasis`, `~/Library/Caches/stasis` on macOS, `%LOCALAPPDATA%\stasis\Cache` on Windows) |
 | `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 |
 

package/bin/stasis.js

@@ -3,9 +3,9 @@
 import { spawn } from 'node:child_process'
 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, parseLeadingOptions, parseResourcesOption } from '@exodus/stasis-core/util'
 import pkg from '../package.json' with { type: 'json' }
@@ -20,19 +20,69 @@ assert(basename(jsname) === 'stasis' || pathsEqual(jsname, fileURLToPath(import.
 
 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] [--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 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] [--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 [--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 [--add] [--output=(path|-)] path/to/file.rs ...
+ 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))
+  --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).)
@@ -43,12 +93,20 @@ function usage(prefix = '') {
  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 [--why|--why-deep] [--why-full] [--reason=consumer] path/to/file ...
- (--why lists, per advisory, the cross-module import paths that pull the package in,
+ 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)
+  --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) ...
  (streams to stdout by default; --output=- is explicit stdout)
 `.trim())
@@ -61,6 +119,14 @@ 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') {
@@ -77,12 +143,13 @@ if (command === '-v' || command === '--version') {
     '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' },
   }
   const values = parseLeadingOptions(argv, options, {
-    valueFlags: ['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--resources', '--brotli-quality'],
+    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')
@@ -115,6 +182,15 @@ if (command === '-v' || command === '--version') {
       usage(`Error: ${cause.message}`)
     }
   }
+  // --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' : ''
   // --package-json: auto-include every bundled module's package.json. Only meaningful while WRITING
@@ -123,7 +199,7 @@ if (command === '-v' || command === '--version') {
     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 }) })
+  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)
@@ -166,6 +242,10 @@ if (command === '-v' || command === '--version') {
   // --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
@@ -173,6 +253,7 @@ if (command === '-v' || command === '--version') {
 } else if (command === 'bundle') {
   const options = {
     mapping: { type: 'string' },
+    manifests: { type: 'boolean' },
     output: { type: 'string', short: 'o' },
     scope: { type: 'string' },
     lockfile: { type: 'string' },
@@ -183,17 +264,30 @@ if (command === '-v' || command === '--version') {
     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' },
   }
   const values = parseLeadingOptions(argv, options, {
-    valueFlags: ['--mapping', '--output', '--scope', '--lockfile', '--conditions', '--mainFields', '--platforms', '--resources', '--brotli-quality', '-o'],
+    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))
@@ -202,6 +296,35 @@ 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')
@@ -223,6 +346,13 @@ if (command === '-v' || command === '--version') {
   // --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
@@ -275,6 +405,8 @@ if (command === '-v' || command === '--version') {
     usage('Error: --platforms is only valid with --metro')
   }
   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) {
@@ -292,6 +424,7 @@ if (command === '-v' || command === '--version') {
     cwd: process.cwd(),
     entries: argv,
     mappingFile: values.mapping,
+    manifests,
     output: values.output,
     scope: values.scope,
     lockfile: values.lockfile,
@@ -302,11 +435,88 @@ if (command === '-v' || command === '--version') {
     platforms,
     jsx,
     flow,
+    typescript,
+    tsconfig: values.tsconfig,
     resources,
     packageJSON,
+    cargo,
+    cargoFeatures,
+    cargoNoDefaultFeatures,
+    cargoAllFeatures,
+    cargoTarget,
+    cargoManifests,
     brotliQuality,
     add,
   })
+} 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.
@@ -409,11 +619,20 @@ 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 })
+  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, { why: Boolean(values.why), whyDeep: Boolean(values['why-deep']), whyFull: Boolean(values['why-full']), reason: values.reason })
+  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') {

package/package.json

@@ -1,46 +1,57 @@
 {
   "name": "@exodus/stasis",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "description": "File-level source bundles and lockfiles",
   "type": "module",
   "exports": {
     "./esbuild": "./src/esbuild.js",
     "./webpack": "./src/webpack.js",
+    "./rollup": "./src/rollup.js",
     "./metro": "./src/metro.js",
     "./metro-transformer": "./src/metro-transformer.js",
     "./loader": "./src/loader.js",
     "./mock": "./src/mock.js",
     "./bundle": "./src/bundle.js",
+    "./bundle-reader": "./src/bundle-reader.js",
     "./cmd/bundle": "./src/cmd/bundle.js",
     "./cmd/build": "./src/cmd/build.js",
     "./diff": "./src/diff.js",
     "./lockfile": "./src/lockfile.js",
     "./prune": "./src/prune.js",
     "./sbom": "./src/sbom.js",
+    "./vfs-bundle": "./src/vfs-bundle.js",
     "./logo.svg": "./logo.svg"
   },
   "files": [
     "bin/stasis.js",
     "logo.svg",
-    "src/apis/npm/index.js",
-    "src/apis/npm/semver.cjs",
+    "src/audit-corrections.js",
     "src/audit.js",
     "src/babel.js",
     "src/babel-worker.cjs",
     "src/bundle.js",
     "src/bundle-from-lockfile.js",
+    "src/bundle-reader.js",
     "src/cmd/bundle.js",
     "src/cmd/build.js",
     "src/cmd/diff.js",
+    "src/cmd/github-bundle.js",
+    "src/cmd/output.js",
     "src/cmd/sbom.js",
     "src/diff.js",
     "src/esbuild.js",
+    "src/json-stream.js",
     "src/loader.js",
     "src/loader-mock.js",
     "src/loaders/bash.js",
+    "src/loaders/cargo.js",
+    "src/loaders/foundry.js",
     "src/loaders/rust.js",
     "src/loaders/solidity.js",
+    "src/loaders/solidity-ownership.js",
+    "src/loaders/toml.js",
     "src/loaders/php.js",
+    "src/loaders/paths.js",
     "src/lockfile.js",
     "src/metro.js",
     "src/metro-resolver.js",
@@ -48,9 +59,19 @@
     "src/mock.js",
     "src/parse.js",
     "src/prune.js",
+    "src/resolve-fields.js",
+    "src/resolve-node.js",
+    "src/resolve-typescript.js",
+    "src/rollup.js",
     "src/sbom.js",
     "src/scan.js",
-    "src/webpack.js"
+    "src/vfs-bundle.js",
+    "src/vfs-bundle/entries.js",
+    "src/vfs-bundle/github.js",
+    "src/vfs-bundle/soldeer.js",
+    "src/vfs-bundle/tree.js",
+    "src/webpack.js",
+    "src/why.js"
   ],
   "engines": {
     "node": ">=24.14.0"
@@ -60,18 +81,24 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ExodusOSS/stasis.git",
+    "url": "git+https://github.com/PreventiveMeasures/stasis.git",
     "directory": "stasis"
   },
   "author": "Exodus Movement, Inc.",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/ExodusOSS/stasis/issues"
+    "url": "https://github.com/PreventiveMeasures/stasis/issues"
   },
-  "homepage": "https://github.com/ExodusOSS/stasis#readme",
+  "homepage": "https://github.com/PreventiveMeasures/stasis#readme",
   "dependencies": {
-    "@exodus/stasis-core": "1.0.0-beta.3",
-    "@exodus/stasis-plugins": "1.0.0-beta.3",
+    "@exodus/bytes": "^1.16.0",
+    "@exodus/stasis-core": "1.0.0-beta.5",
+    "@exodus/stasis-plugins": "1.0.0-beta.5",
+    "@preventive/archive": "1.0.0-beta.3",
+    "@preventive/deptree": "1.0.0-alpha.6",
+    "@preventive/lockfile": "1.0.0-alpha.5",
+    "@preventive/upstream": "1.0.0-alpha.4",
+    "@preventive/vfs": "1.0.0-beta.3",
     "oxc-parser": "^0.94.0"
   },
   "peerDependencies": {

package/src/audit-corrections.js

@@ -0,0 +1,68 @@
+import { satisfies, valid } from '@preventive/upstream/semver.js'
+
+// Manual corrections to audit findings: files that must NOT count as evidence
+// that a (potentially vulnerable) package's code is present. An import edge whose
+// target is one of these files is not evidence the package is really used, so a
+// package pulled in only through corrected files is skipped by the audit (see
+// collectPackagesFromFile) -- none of its real code ships, so no advisory applies.
+//
+// Each entry names a package, the audit-irrelevant files (relative to the module
+// dir), and `range` -- the semver range VERIFIED to match the rationale. The
+// correction never applies outside it: a release could change the file, so the
+// range is widened only after re-checking the file in the new versions.
+const CORRECTIONS = [
+  {
+    // ws's browser build is a noop stub -- `module.exports = function () { throw
+    // new Error('ws does not work in the browser...') }` -- with none of the
+    // WebSocket implementation in it. Verified against the ws 8.21.1 tarball
+    // (latest at the time of writing); re-check browser.js before widening.
+    name: 'ws',
+    files: new Set(['browser.js']),
+    range: '<=8.21.1',
+  },
+  {
+    // node-fetch's browser build re-exports the environment's native fetch
+    // (`module.exports = globalObject.fetch`, plus Headers/Request/Response) --
+    // none of the node-fetch implementation, where its advisories live, is in it.
+    // browser.js ships only through 2.7.0 (3.x dropped it); verified 2.6.13/2.7.0.
+    name: 'node-fetch',
+    files: new Set(['browser.js']),
+    range: '<=2.7.0',
+  },
+]
+
+// Is `rel` (a file path relative to the module dir) audit-irrelevant for
+// `name@version`? Unknown or unparsable versions are never corrected (fail
+// closed: the package stays audited).
+function isCorrectedFile(name, version, rel) {
+  for (const { name: pkg, files, range } of CORRECTIONS) {
+    if (pkg !== name || !files.has(rel)) continue
+    if (valid(version) && satisfies(version, range)) return true
+  }
+  return false
+}
+
+// A manifest (top-level or nested) is never code: the resolution graph records
+// resolver/metadata reads of `package.json` as edges (react-native scans sibling
+// packages' manifests for Haste/asset resolution) and consumers record them
+// alongside bundled files, but no package code ships through one. So too for the
+// manifests the other ecosystems' bundles carry beside a dependency's code
+// (--cargo-manifests, --manifests): its Cargo.toml and the checksums cargo vendored
+// it with, its composer.json, a Solidity dependency's foundry.toml and remappings.
+const MANIFESTS = {
+  npm: new Set(['package.json']),
+  cargo: new Set(['Cargo.toml', 'Cargo.lock', '.cargo-checksum.json']),
+  composer: new Set(['composer.json', 'composer.lock']),
+  soldeer: new Set(['package.json', 'foundry.toml', 'remappings.txt', 'soldeer.toml']),
+  github: new Set(['package.json', 'foundry.toml', 'remappings.txt', 'soldeer.toml']),
+}
+const isManifest = (rel, ecosystem) => MANIFESTS[ecosystem]?.has(rel.slice(rel.lastIndexOf('/') + 1)) ?? false
+
+// Is `rel` evidence that `name@version`'s REAL code is present, of a dependency of
+// `ecosystem` (npm by default)? This is the one rule every audit surface shares --
+// package presence, the reason column, and the --why chain graph all count a file
+// (or an edge targeting it) only when it passes. Manifests never do; corrected
+// files (npm's) don't within their verified range.
+export function isEvidenceFile(name, version, rel, ecosystem = 'npm') {
+  return !isManifest(rel, ecosystem) && (ecosystem !== 'npm' || !isCorrectedFile(name, version, rel))
+}