@exodus/stasis 1.0.0-alpha.3 → 1.0.0-beta.1

package/README.md

@@ -1,10 +1,74 @@
 # <img src="./logo.svg" alt="" width="39" height="39" valign="bottom" /> `@exodus/stasis`
 
-Analyzeable source code bundles with resolutions + per-file lockfiles
+*Analyzeable source code bundles with resolutions + fine-grained lockfiles.*
 
-## Bundles
+Both lockfiles and bundles only include what is actually _used_.\
+Generally about 10x smaller than production-focused `node_modules` install.
 
-## Lockfiles
+Enforcing these lets you focus automated code scanning and alerts only on code that matters,
+and makes the analysis import graph aware.
+
+Ideal workflow: create bundle -> analyze -> ship _that exact bundle_ to production.
+
+Lockfile can attest the bundle in a readable form, but that's not required - bundle itself can be an attestation.
+
+| Lockfile | Bundle |
+| -------- | ------ |
+| `stasis.lock.json` | `stasis.code.br` |
+| Asserts per-file content integrity and the import graph | Contains per-file content (source) and the import graph |
+| Human-readable | Compressed |
+| Asserts only, files are read from disk | Loads or asserts (can be used as a lockfile)|
+| Modes: `add`, `replace`, `frozen`, `ignore` | Modes: `load`, `add`, `replace`, `frozen`, `ignore` |
+
+The main difference between lockfiles and bundles is that lockfiles contain integrities, and bundles contain full content.\
+See [file formats](https://github.com/ExodusOSS/stasis/blob/main/doc/file-formats.md).
+
+Both can be run in full scope (default) or just in `node_modules` scope.
+
+## Why a separate bundle format?
+
+| | Stasis | JS bundlers | Sourcemaps | SEA | source + deps tarball | Containers |
+| - | - | - | - | - | - | - |
+| Runnable | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ |
+| Contains original sources | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ |
+| Sources match runtime | ✅ | ➖ | ❌ Deps can misreport | ➖ | ✅ | ✅ |
+| Dependency versions | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ |
+| Import edges | ✅ | ❌ | ❌ | ❌ | 🔍 Implicit | 🔍 Implicit |
+| Constrained to related code | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
+
+_Lockfiles (npm/pnpm/etc) not mentioned: they are like the "tarball" column, but also require network, install step and are not self-contained._
+
+## Commands
+
+| Command | What it does |
+| - | - |
+| `stasis run --lock=add app.js` | build just a lockfile |
+| `stasis run --lock=frozen app.js` | verify disk against the lockfile |
+| `stasis run --bundle=add app.js` | build just a bundle |
+| `stasis run --bundle=frozen app.js` | verify disk against the bundle alone (self-attesting) |
+| `stasis run --bundle=load app.js` | run from the bundle alone |
+| `stasis run --lock=add --bundle=add app.js` | build a lockfile and bundle together |
+| `stasis run --lock=frozen --bundle=load app.js` | run from the bundle, verified against the lockfile |
+| `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 bundle src/index.js` | build a bundle statically, without executing it |
+| `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 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 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).
 
 ## License
 

package/bin/stasis.js

@@ -4,8 +4,9 @@ import { spawn } from 'node:child_process'
 import { parseArgs } from 'node:util'
 import { once } from 'node:events'
 import { fileURLToPath } from 'node:url'
-import { basename, resolve } from 'node:path'
+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 pkg from '../package.json' with { type: 'json' }
 
@@ -19,10 +20,21 @@ 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|ignore)] [--bundle-file=path/to/bundle.br] [--full] path/to/file.js ...
- stasis bundle [--mapping=path/to/remappings(.txt|.toml)] [--output=path/to/out.stasis.code.br] 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] [--mock] [--fs=(sync|async)] [--resources=ext,ext] 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)
+ 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 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 sbom --format=(spdx|cyclonedx) [--output=(path|-)] path/to/(lockfile|bundle) ...
+ (stasis sbom streams to stdout by default; --output=- is explicit stdout)
 `.trim())
   process.exit(1)
 }
@@ -40,7 +52,7 @@ if (command === '-v' || command === '--version') {
   process.exit(0)
 } else if (command === 'run') {
   const flags = []
-  const valueFlags = new Set(['--bundle', '--bundle-file', '--lock'])
+  const valueFlags = new Set(['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--resources'])
   while (argv.length > 0 && (argv[0].startsWith('-') || valueFlags.has(flags.at(-1)))) {
     flags.push(argv.shift())
   }
@@ -49,41 +61,131 @@ if (command === '-v' || command === '--version') {
     lock: { type: 'string', default: 'none' },
     bundle: { type: 'string', default: 'none' },
     'bundle-file': { type: 'string' },
+    'resources-bundle-file': { type: 'string' },
     debug: { type: 'boolean' },
-    full: { type: 'boolean' },
+    dependencies: { type: 'boolean' },
+    'child-process': { type: 'boolean' },
+    mock: { type: 'boolean' },
+    fs: { type: 'string' },
+    resources: { type: 'string' },
   }
 
-  const { values } = parseArgs({ args: flags, options })
+  let values
+  try {
+    ({ values } = parseArgs({ args: flags, options }))
+  } catch (cause) {
+    usage(`Error: ${cause.message}`)
+  }
   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
-  const scope = values.full ? 'full' : 'node_modules'
+  const scope = values.dependencies ? 'node_modules' : 'full'
   const bundle = values.bundle
   const bundleFile = values['bundle-file'] ? resolve(values['bundle-file']) : ''
+  const resourcesBundleFile = values['resources-bundle-file'] ? resolve(values['resources-bundle-file']) : ''
   const debug = values.debug ? '1' : ''
-  if (!['none', 'ignore', 'add', 'replace', 'load'].includes(bundle)) usage('Error: invalid --bundle value')
-  if (bundleFile && bundle === 'none') usage('Error: --bundle-file requires --bundle=(add|replace|load|ignore)')
-  if (bundle === 'load' && lock !== 'frozen' && lock !== 'none' && lock !== 'ignore') usage('Error: --bundle=load requires --lock=(frozen|none|ignore)')
-  if (lock === 'none' && bundle === 'none') usage('Error: --lock=none requires --bundle=(add|replace|load|ignore)')
-  console.warn('[stasis] Running stasis with config:', { lock, scope, bundle, ...(bundleFile && { bundleFile }) })
+  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.
+  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.
+  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.
+  const resources = values.resources ?? ''
+  // --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.
+  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 }) })
   if (debug) console.warn(`[stasis] Warning: stasis debug mode active`)
   setEnv('EXODUS_STASIS_LOCK', lock)
   setEnv('EXODUS_STASIS_SCOPE', scope)
   setEnv('EXODUS_STASIS_BUNDLE', bundle)
   setEnv('EXODUS_STASIS_BUNDLE_FILE', bundleFile)
+  setEnv('EXODUS_STASIS_RESOURCES_BUNDLE_FILE', resourcesBundleFile)
   setEnv('EXODUS_STASIS_DEBUG', debug)
-  const child = spawn('node', ['--import', import.meta.resolve('../src/loader.js'), ...argv], { stdio: 'inherit' })
-  const [code] = await once(child, 'close')
-  process.exitCode = code
+  setEnv('EXODUS_STASIS_CHILD_PROCESS', childProcess)
+  setEnv('EXODUS_STASIS_FS', captureFs)
+  setEnv('EXODUS_STASIS_RESOURCES', resources)
+  // --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).
+  // 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.)
+    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.
+      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
+    }
+    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).
+    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).
+  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' })
+  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', '-o'])
+  const valueFlags = new Set(['--mapping', '--output', '--scope', '--lockfile', '--conditions', '--mainFields', '--platforms', '-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' },
+    scope: { type: 'string' },
+    lockfile: { type: 'string' },
+    conditions: { type: 'string' },
+    mainFields: { type: 'string' },
+    metro: { type: 'boolean' },
+    platforms: { type: 'string', multiple: true },
   }
   let values
   try {
@@ -91,19 +193,198 @@ if (command === '-v' || command === '--version') {
   } catch (cause) {
     usage(`Error: ${cause.message}`)
   }
-  if (argv.length === 0) usage('Nothing to bundle: no .sol file given')
-  if (!argv.every((f) => f.endsWith('.sol'))) usage('Error: bundle only accepts .sol files')
+  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'))
+  const allJs = argv.every((f) => /\.(?:js|cjs|mjs|ts|cts|mts)$/u.test(f))
+  const allBash = argv.every((f) => /\.(?:sh|bash)$/u.test(f))
+  const allRust = argv.every((f) => f.endsWith('.rs'))
+  if (!allSol && !allPhp && !allJs && !allBash && !allRust) {
+    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')
+  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.
+  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.
+  if (values.conditions !== undefined && !allJs) usage('Error: --conditions is only valid for JS bundles')
+  const conditions = values.conditions === undefined
+    ? []
+    : values.conditions.split(',').map((s) => s.trim()).filter(Boolean)
+  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.
+  if (values.mainFields !== undefined && !allJs) usage('Error: --mainFields is only valid for JS bundles')
+  const mainFields = values.mainFields === undefined
+    ? undefined
+    : values.mainFields.split(',').map((s) => s.trim()).filter(Boolean)
+  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.
+  const metro = Boolean(values.metro)
+  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).
+  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')
+  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)")
+    if (platforms.length === 0) usage('Error: --metro requires --platforms (e.g. --platforms=ios,android)')
+  } else if (platforms.length > 0) {
+    usage('Error: --platforms is only valid with --metro')
+  }
   const { bundleCommand } = await import('../src/cmd/bundle.js')
   await bundleCommand({
     cwd: process.cwd(),
     entries: argv,
     mappingFile: values.mapping,
     output: values.output,
+    scope: values.scope,
+    lockfile: values.lockfile,
+    conditions,
+    mainFields,
+    metro,
+    platforms,
+  })
+} 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' },
+    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.
+    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}`)
+  }
+  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.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 `-`.
+  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.
+  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.
+  const loader = {}
+  for (const entry of values.loader ?? []) {
+    const colon = entry.indexOf(':')
+    if (colon <= 0 || !entry.startsWith('.')) usage(`Error: --loader must be .EXT:LOADER (got '${entry}')`)
+    loader[entry.slice(0, colon)] = entry.slice(colon + 1)
+  }
+  const { buildCommand } = await import('../src/cmd/build.js')
+  await buildCommand({
+    cwd: process.cwd(),
+    artifact: argv[0],
+    entry: argv[1],
+    output: values.output,
+    format: values.format,
+    platform: values.platform,
+    minify: values.minify,
+    sourcemap: values.sourcemap,
+    define,
+    external: values.external ?? [],
+    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}`)
+  }
+  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 })
+} 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.
+  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.
+  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).
+  process.exitCode = differences ? 1 : 0
 } else if (command === 'prune') {
   if (argv.length > 1) usage('Error: prune takes at most one path argument')
   const root = argv[0] ? resolve(argv[0]) : process.cwd()
-  const { prune } = await import('../src/prune.js')
+  const { prune } = await import('@exodus/stasis-core/prune')
   const { removed, validated } = prune({ root })
   console.warn(`[stasis] prune: validated ${validated.length} file(s), removed ${removed.length} file(s)`)
 } else if (command === 'audit') {
@@ -113,6 +394,32 @@ if (command === '-v' || command === '--version') {
   const report = await audit(files)
   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}`)
+  }
+  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')
+  const { sbomCommand } = await import('../src/cmd/sbom.js')
+  sbomCommand({
+    cwd: process.cwd(),
+    files: argv,
+    format: values.format,
+    output: values.output,
+  })
 } else {
   usage()
 }

package/logo.svg

@@ -1,11 +1,20 @@
 <svg xmlns="http://www.w3.org/2000/svg" aria-label="Stasis" viewBox="0 0 128 128">
   <defs>
-    <linearGradient id="a" x1="0" x2="1" y1="0" y2="1">
+    <linearGradient id="b" x1="0" x2="1" y1="0" y2="1">
       <stop offset="0%" stop-color="#1f9cff"/>
       <stop offset="60%" stop-color="#8c5bfe"/>
       <stop offset="100%" stop-color="#b85bfe"/>
     </linearGradient>
+    <clipPath id="a">
+      <rect width="126.5" height="126.5" x=".75" y=".75" rx="27.25" ry="27.25"/>
+    </clipPath>
   </defs>
-  <rect width="128" height="128" fill="rgba(150,150,150,0.09)" rx="28" ry="28"/>
-  <circle cx="64" cy="64" r="28.16" fill="url(#a)"/>
+  <rect width="128" height="128" fill="#969696" fill-opacity=".09" rx="28" ry="28"/>
+  <g fill="none" stroke="#8c8c8c" stroke-width="1.5" opacity=".42">
+    <g clip-path="url(#a)">
+      <path d="M0 12 12 0M0 26.5 26.5 0M0 41 41 0M0 55.5 55.5 0M0 70 70 0M0 84.5 84.5 0M0 99 99 0M0 113.5 113.5 0M0 128 128 0M14.5 128 128 14.5M29 128l99-99m-84.5 99L128 43.5M58 128l70-70m-55.5 70L128 72.5M87 128l41-41m-26.5 41 26.5-26.5M116 128l12-12"/>
+    </g>
+    <rect width="126.5" height="126.5" x=".75" y=".75" rx="27.25" ry="27.25"/>
+  </g>
+  <circle cx="64" cy="64" r="28.16" fill="url(#b)"/>
 </svg>

package/package.json

@@ -1,15 +1,22 @@
 {
   "name": "@exodus/stasis",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-beta.1",
   "description": "File-level source bundles and lockfiles",
   "type": "module",
   "exports": {
     "./esbuild": "./src/esbuild.js",
     "./webpack": "./src/webpack.js",
+    "./metro": "./src/metro.js",
+    "./metro-transformer": "./src/metro-transformer.js",
     "./loader": "./src/loader.js",
+    "./mock": "./src/mock.js",
     "./bundle": "./src/bundle.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",
     "./logo.svg": "./logo.svg"
   },
   "files": [
@@ -19,16 +26,28 @@
     "src/apis/npm/semver.cjs",
     "src/audit.js",
     "src/bundle.js",
+    "src/bundle-from-lockfile.js",
     "src/cmd/bundle.js",
-    "src/config.js",
+    "src/cmd/build.js",
+    "src/cmd/diff.js",
+    "src/cmd/extract.js",
+    "src/cmd/sbom.js",
+    "src/diff.js",
     "src/esbuild.js",
     "src/loader.js",
+    "src/loader-mock.js",
+    "src/loaders/bash.js",
+    "src/loaders/rust.js",
     "src/loaders/solidity.js",
+    "src/loaders/php.js",
     "src/lockfile.js",
+    "src/metro.js",
+    "src/metro-transformer.js",
+    "src/mock.js",
+    "src/parse.js",
     "src/prune.js",
-    "src/state.js",
-    "src/state.util.js",
-    "src/util.js",
+    "src/sbom.js",
+    "src/scan.js",
     "src/webpack.js"
   ],
   "engines": {
@@ -37,14 +56,10 @@
   "bin": {
     "stasis": "bin/stasis.js"
   },
-  "scripts": {
-    "lint": "oxlint",
-    "test": "node --run test:coherence",
-    "test:coherence": "node --test"
-  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ExodusOSS/stasis.git"
+    "url": "git+https://github.com/ExodusOSS/stasis.git",
+    "directory": "stasis"
   },
   "author": "Exodus Movement, Inc.",
   "license": "MIT",
@@ -52,12 +67,17 @@
     "url": "https://github.com/ExodusOSS/stasis/issues"
   },
   "homepage": "https://github.com/ExodusOSS/stasis#readme",
-  "devDependencies": {
-    "@exodus/bytes": "^1.15.0",
-    "esbuild": "^0.27.3",
-    "oxlint": "^1.52.0",
-    "string-replace-loader": "^2.3.0",
-    "webpack": "^4.47.0"
+  "dependencies": {
+    "@exodus/stasis-core": "1.0.0-beta.1",
+    "@exodus/stasis-plugins": "1.0.0-beta.1",
+    "oxc-parser": "^0.94.0"
+  },
+  "peerDependencies": {
+    "esbuild": "*"
   },
-  "packageManager": "pnpm@10.33.4+sha512.1c67b3b359b2d408119ba1ed289f34b8fc3c6873412bec6fd264fbdc82489e510fcbecb9ce9d22dae7f3b76269d8441046014bdca53b9979cd7a561ad631b800"
+  "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    }
+  }
 }