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

package/bin/stasis.js

@@ -8,6 +8,7 @@ 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 pkg from '../package.json' with { type: 'json' }
 
 const argv = [...process.argv]
@@ -20,14 +21,15 @@ 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] [--mock] [--fs=(sync|async)] [--resources=ext,ext] path/to/file.js ...
+ 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)
+ (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 extract [--output=path/to/dir] path/to/bundle.stasis.code.br
  stasis diff --stat [--imports] path/to/(lockfile|bundle) path/to/(lockfile|bundle)
@@ -52,7 +54,7 @@ if (command === '-v' || command === '--version') {
   process.exit(0)
 } else if (command === 'run') {
   const flags = []
-  const valueFlags = new Set(['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--resources'])
+  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())
   }
@@ -68,6 +70,7 @@ if (command === '-v' || command === '--version') {
     mock: { type: 'boolean' },
     fs: { type: 'string' },
     resources: { type: 'string' },
+    'brotli-quality': { type: 'string' },
   }
 
   let values
@@ -104,10 +107,19 @@ if (command === '-v' || command === '--version') {
   // --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 ?? ''
+  // --brotli-quality: bundle compression quality (0..11; unset = brotli's default 11).
+  let brotliQuality
+  if (values['brotli-quality'] !== undefined) {
+    try {
+      brotliQuality = parseBrotliQuality('--brotli-quality', values['brotli-quality'])
+    } catch (cause) {
+      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.
   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 }) })
+  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 }) })
   if (debug) console.warn(`[stasis] Warning: stasis debug mode active`)
   setEnv('EXODUS_STASIS_LOCK', lock)
   setEnv('EXODUS_STASIS_SCOPE', scope)
@@ -118,6 +130,9 @@ if (command === '-v' || command === '--version') {
   setEnv('EXODUS_STASIS_CHILD_PROCESS', childProcess)
   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).
+  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
@@ -173,7 +188,7 @@ if (command === '-v' || command === '--version') {
   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', '-o'])
+  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())
   }
@@ -186,6 +201,7 @@ if (command === '-v' || command === '--version') {
     mainFields: { type: 'string' },
     metro: { type: 'boolean' },
     platforms: { type: 'string', multiple: true },
+    'brotli-quality': { type: 'string' },
   }
   let values
   try {
@@ -255,6 +271,15 @@ 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).
+  let brotliQuality
+  if (values['brotli-quality'] !== undefined) {
+    try {
+      brotliQuality = parseBrotliQuality('--brotli-quality', values['brotli-quality'])
+    } catch (cause) {
+      usage(`Error: ${cause.message}`)
+    }
+  }
   const { bundleCommand } = await import('../src/cmd/bundle.js')
   await bundleCommand({
     cwd: process.cwd(),
@@ -267,6 +292,7 @@ if (command === '-v' || command === '--version') {
     mainFields,
     metro,
     platforms,
+    brotliQuality,
   })
 } else if (command === 'build') {
   const flags = []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/stasis",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "description": "File-level source bundles and lockfiles",
   "type": "module",
   "exports": {
@@ -68,8 +68,8 @@
   },
   "homepage": "https://github.com/ExodusOSS/stasis#readme",
   "dependencies": {
-    "@exodus/stasis-core": "1.0.0-beta.1",
-    "@exodus/stasis-plugins": "1.0.0-beta.1",
+    "@exodus/stasis-core": "1.0.0-beta.2",
+    "@exodus/stasis-plugins": "1.0.0-beta.2",
     "oxc-parser": "^0.94.0"
   },
   "peerDependencies": {

package/src/cmd/build.js

@@ -21,13 +21,14 @@ export { bundleFromLockfile }
 const JS_EXTS = new Set(['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts', '.jsx', '.tsx'])
 
 // Allowlist (NOT a blocklist) of per-file formats `stasis build` accepts in an artifact:
-// the JS/TS/JSON code formats esbuild builds, plus the non-code payload formats
-// (resource/directory) that are inert unless the SELECTED entry imports them. An allowlist
+// the JS/TS/JSON code formats esbuild builds, plus the non-code formats -- resource/
+// directory payloads and the payload-free stat records (`--fs` lstat/stat captures) --
+// that are inert unless the SELECTED entry imports them. An allowlist
 // so a new language format added to `stasis bundle` later (e.g. a future `go`) is rejected
 // here by default, rather than slipping through to a cryptic esbuild failure in the build.
 const BUILDABLE_FORMATS = new Set([
   'module', 'commonjs', 'json', 'module-typescript', 'commonjs-typescript',
-  'resource', 'resource:base64', 'directory',
+  'resource', 'resource:base64', 'directory', 'stat:file', 'stat:directory',
 ])
 
 // esbuild is an OPTIONAL peer dependency: `stasis build` is the only command that

package/src/cmd/bundle.js

@@ -1020,7 +1020,9 @@ const DEFAULT_BUNDLE_FILE = 'stasis.code.br'
 // so it resolves different files on disk and fails closed (correctly -- the lockfile
 // genuinely attests a different graph). Pair such a lockfile with `--bundle=load`, or
 // replay the same `--conditions` at run time, so the attested and observed graphs agree.
-export async function bundleCommand({ cwd = process.cwd(), entries, mappingFile, output, scope, lockfile, conditions, mainFields, platforms, metro } = {}) {
+// `brotliQuality` (integer 0..11, optional; unset = brotli's default 11) tunes the
+// output compression, forwarded to brotliOptions().
+export async function bundleCommand({ cwd = process.cwd(), entries, mappingFile, output, scope, lockfile, conditions, mainFields, platforms, metro, brotliQuality } = {}) {
   const kind = classifyEntries('bundleCommand', { entries, mappingFile, scope, lockfile, conditions, mainFields, platforms, metro })
 
   let bundle
@@ -1053,7 +1055,7 @@ export async function bundleCommand({ cwd = process.cwd(), entries, mappingFile,
   const files = [...bundle.sources.keys()]
   const modules = bundle.modules
 
-  const data = brotliCompressSync(serialized, brotliOptions())
+  const data = brotliCompressSync(serialized, brotliOptions(brotliQuality))
   // Default to writing stasis.code.br in cwd; `-` is the conventional opt-in
   // for streaming the raw brotli bytes to stdout (e.g. to pipe somewhere else).
   const target = output ?? DEFAULT_BUNDLE_FILE

package/src/metro-transformer.js

@@ -1,6 +1,7 @@
 // Public-export adapter: backs `@exodus/stasis/metro-transformer`. The transformer
 // lives in @exodus/stasis-plugins (which depends on @exodus/stasis-core for State; it
-// drives load-mode getFile directly). Wire it as Metro's `transformer.transformerPath`
-// in load mode; see the source for the load asymmetry that lets this run per-worker
+// drives load-mode getFile directly). Wire it permanently as Metro's top-level
+// `transformerPath`; it only acts under bundle=load (transparent pass-through
+// otherwise). See the source for the load asymmetry that lets this run per-worker
 // without cross-worker state sync.
 export * from '@exodus/stasis-plugins/metro-transformer'