@exodus/stasis-plugins 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Exodus Movement
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# <img src="/stasis/logo.svg" alt="" width="39" height="39" valign="bottom" /> `@exodus/stasis-plugins`
+
+Bundler plugins (webpack, esbuild, Metro) for `@exodus/stasis-core`.
+
+See main package [GitHub](https://github.com/ExodusOSS/stasis/tree/main/stasis) or [npm](https://npmjs.com/package/@exodus/stasis) for full README.
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@exodus/stasis-plugins",
+  "version": "1.0.0-beta.0",
+  "description": "Bundler plugins (webpack, esbuild, Metro) for @exodus/stasis-core",
+  "type": "module",
+  "exports": {
+    "./webpack": "./src/webpack.js",
+    "./esbuild": "./src/esbuild.js",
+    "./metro": "./src/metro.js",
+    "./metro-transformer": "./src/metro-transformer.js"
+  },
+  "files": [
+    "src/esbuild.js",
+    "src/metro.js",
+    "src/metro-transformer.js",
+    "src/plugins.js",
+    "src/webpack.js"
+  ],
+  "engines": {
+    "node": ">=24.14.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExodusOSS/stasis.git",
+    "directory": "stasis-plugins"
+  },
+  "author": "Exodus Movement, Inc.",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ExodusOSS/stasis/issues"
+  },
+  "homepage": "https://github.com/ExodusOSS/stasis#readme",
+  "dependencies": {
+    "@exodus/stasis-core": "1.0.0-beta.0"
+  }
+}

package/src/esbuild.js

@@ -0,0 +1,224 @@
+import { isUtf8 } from 'node:buffer'
+import { isBuiltin } from 'node:module'
+import { extname, resolve as resolvePath } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import assert from 'node:assert/strict'
+
+import { Bundle } from '@exodus/stasis-core/bundle'
+import { resolvePluginState } from './plugins.js'
+import { State } from '@exodus/stasis-core/state'
+// Pre-patch snapshot, NOT `import { readFile } from 'node:fs/promises'`: under
+// `stasis run --fs=async` that builtin is monkey-patched, and this plugin loads after
+// the patch, so a direct import would route esbuild's own source reads through the
+// --fs capture hook. The snapshot in state-util (taken during the --import preload) is
+// the genuine reader.
+import { realReadFile } from '@exodus/stasis-core/state-util'
+import { classifyExtension } from '@exodus/stasis-core/util'
+
+export class StasisEsbuild {
+  #seen = new Set()
+  #state
+  #resources
+  #loaders
+
+  constructor(options = {}, { loaders } = {}) {
+    // A caller that owns a State (e.g. `stasis build`) can pass it directly to drive the plugin, bypassing resolvePluginState; mode follows that State's config, and a foreign-copy State fails closed via the instanceof miss.
+    const state = options instanceof State
+      ? options
+      : resolvePluginState('StasisEsbuild', options, process.cwd()).state
+    this.#state = state  // null when plugin should be inert
+    // resources is a Config field now (validated + coordinated against any preload in
+    // resolvePluginState); cache the resolved Set for the per-file classify hot path.
+    this.#resources = state?.config.resources ?? new Set()
+    // Per-extension esbuild loader overrides (e.g. { '.js' -> 'jsx' } so a .js file
+    // carrying JSX -- the React Native convention -- parses; esbuild's default 'js'
+    // loader rejects JSX). Keyed by extname WITH the dot; falls back to the
+    // extension-derived loader (see #loaderFor) when an extension isn't overridden.
+    this.#loaders = loaders ?? new Map()
+  }
+
+  // The esbuild loader for a served file: an explicit per-extension override if the
+  // caller configured one, else derived from the extension (.cjs/.mjs/.cts/.mts strip
+  // their leading module letter to js/ts; other code extensions map 1:1 to a loader).
+  #loaderFor(path) {
+    const ext = extname(path)
+    return this.#loaders.get(ext) ?? ext.replace(/^\.[cm]?/u, '')
+  }
+
+  get name() {
+    return 'stasis'
+  }
+
+  setup = ({ onResolve, onLoad, onEnd, resolve }) => {
+    if (!this.#state) return  // noop plugin
+
+    // The stasis preload owns its own write via beforeExit/exit hooks (stasis-core/hooks.js).
+    // Standalone and sidecar States have no such hook, so the plugin writes them when the
+    // build finishes -- but only on a clean build, otherwise a partial bundle/lockfile
+    // would overwrite the user's good file.
+    if (this.#state !== State.preload) {
+      onEnd((result) => {
+        if (result.errors.length > 0) return
+        this.#state.write()
+      })
+    }
+
+    // Load mode: resolution comes from the bundle's import map, not esbuild's
+    // resolver. The on-disk file may not even exist -- the bundle is the source
+    // of truth (mirrors `stasis run --bundle=load`; see stasis-core/src/hooks.js).
+    // We keep `namespace: 'file'` with the original absolute path, even though the
+    // file isn't on disk: esbuild stats the path only when its own default resolver
+    // produced it; paths returned from a plugin's onResolve are trusted as-is. That
+    // gives the same output bytes as a capture-mode build -- esbuild's path-banner
+    // comments, asset names, and source maps all use the original paths.
+    onResolve({ filter: /$/ }, ({ path: specifier, importer, kind: resolveKind, with: attrs }) => {
+      if (!this.#state.config.loadBundle) return undefined
+      // Node built-ins (`constants`, `node:fs`, ...) are never carried in the bundle
+      // and never recorded as import edges -- the capture side (and the Node run
+      // loader, stasis-core/hooks.js) defer isBuiltin() specifiers before addImport
+      // sees them. Returning undefined hands the builtin back to esbuild's own
+      // resolution, which externalizes it under platform:'node' exactly as in a build
+      // without this plugin; state.getImport would instead throw ERR_MODULE_NOT_FOUND
+      // ("Cannot find module 'constants' imported from <file>"). Mirrors the webpack
+      // plugin's load-mode builtin guard.
+      if (isBuiltin(specifier)) return undefined
+      const isEntry = resolveKind === 'entry-point'
+      let url
+      if (isEntry) {
+        // esbuild's entryPoints are typically absolute, but a bare/relative entry
+        // is anchored to cwd just like the run loader does (resolvePath(cwd, ...))
+        // so the entry file doesn't need to be on disk.
+        url = specifier.startsWith('file:')
+          ? specifier
+          : pathToFileURL(resolvePath(process.cwd(), specifier)).toString()
+        if (this.#state.config.full) this.#state.assertEntry(url)
+      } else {
+        const parentURL = pathToFileURL(importer).toString()
+        // Forward import attributes (e.g. `with { type: 'json' }`) so a
+        // plugin-captured bundle round-trips to plugin-load symmetrically: both
+        // sides key the edge under `* (with: ...)` (no conditions because the
+        // plugin doesn't know them). KNOWN GAP: a bundle captured by the Node
+        // run loader keys edges under specific conditions like `node, import,
+        // ... (with: ...)`; the plugin's `*`-keyed lookup misses that, and the
+        // wildcard fallback in state.getImport only falls back to `*` (without
+        // attrs), so a Node-loader-captured bundle with attributed imports
+        // won't reload via the esbuild plugin without further work
+        // (state.getImport would need a multi-conditions match scan, or the
+        // Node loader would need to mirror under '*' too).
+        try {
+          ;({ url } = this.#state.getImport(parentURL, specifier, { importAttributes: attrs }))
+        } catch (err) {
+          // No attested edge. getImport tried the recorded edge under every conditions
+          // bucket (resolveBundled), so a miss means the request names nothing the
+          // bundle carries -- at a successful capture it was an EXTERNAL (a user
+          // `external` entry; built-ins are handled above). Externals are never recorded
+          // as edges, so return undefined to hand it back to esbuild, which externalizes it as it would
+          // without this plugin. This relaxes only the resolve-time edge lookup:
+          // a genuinely missing in-scope FILE still fails closed at onLoad
+          // (state.getFile serves in-scope bytes from the bundle or throws), so no
+          // disk fallback is introduced. A non-MODULE_NOT_FOUND error is a real
+          // fault -- rethrow it.
+          if (err?.code === 'ERR_MODULE_NOT_FOUND') return undefined
+          throw err
+        }
+      }
+      const format = this.#state.getFormat(url)
+      const kind = Bundle.isResourceFormat(format) ? 'resource' : 'code'
+      return { path: fileURLToPath(url), namespace: 'file', pluginData: { isEntry, kind } }
+    })
+
+    onResolve({ filter: /$/, namespace: 'file' }, async ({ path: specifier, with: attrs, ...args }) => {
+      const isEntry = !args.importer
+
+      // Recurse with a synthetic namespace so esbuild's default resolver runs without re-entering us
+      const res = await resolve(specifier, { ...args, with: attrs, namespace: 'stasis' })
+      if (res.errors.length > 0) return res
+      // Warnings from sibling plugins or esbuild itself (deprecation notices, etc.) are
+      // not our concern -- propagate them upward, don't crash.
+      // A non-empty `suffix` is set by sibling plugins that want to preserve a
+      // query-style suffix on the resolved path (some CSS-modules plugins do).
+      // stasis doesn't know how to persist suffixes to the bundle, so we refuse
+      // them explicitly rather than silently dropping the suffix at capture time.
+      assert.equal(res.suffix, '',
+        `StasisEsbuild: a sibling plugin set res.suffix='${res.suffix}' on '${specifier}'; ` +
+        `stasis can't persist suffixes to the bundle. Disable that plugin or drop suffix from its resolve result.`)
+
+      let kind = 'skip'
+      if (res.namespace === 'file' && !res.external) {
+        kind = classifyExtension(res.path, this.#resources)
+        if (kind === 'unknown') {
+          return {
+            errors: [{
+              text: `StasisEsbuild: unsupported extension for '${res.path}' -- add its extension or filename to the plugin's resources option or stop importing it`,
+            }],
+          }
+        }
+        if (kind === 'code' && !isEntry) {
+          const parentURL = pathToFileURL(args.importer).toString()
+          const url = pathToFileURL(res.path).toString()
+          // Forward import attributes (e.g. `with { type: 'json' }`) symmetrically
+          // with the load path: addImport stores under a conditions-with-attributes
+          // key when attributes are present, so getImport at load time can find
+          // the same edge.
+          this.#state.addImport(parentURL, specifier, url, { importAttributes: attrs })
+        }
+      }
+
+      return { ...res, pluginData: { ...res.pluginData, isEntry, kind } }
+    })
+
+    onLoad({ filter: /$/, namespace: 'file' }, async ({ path, pluginData, with: attrs }) => {
+      const kind = pluginData?.kind ?? 'skip'
+      if (kind === 'skip') return undefined
+      // Accept the `type` import attribute (e.g. `with { type: 'json' }`); reject
+      // anything else loudly since saving import-attribute state to the lockfile
+      // isn't designed yet.
+      for (const k of Object.keys(attrs)) {
+        assert.equal(k, 'type', `unsupported import attribute: ${k}`)
+      }
+
+      // Load mode: serve bytes the bundle attested. `getFile` verifies the hash
+      // against the lockfile (when one is loaded), and throws on a file the
+      // bundle doesn't carry -- a missing in-scope file is a hard error, not a
+      // silent disk fallback. Resources return `{ contents }` only; esbuild's
+      // loader config (file/dataurl/copy/...) interprets and emits them by
+      // extension, the same way capture mode lets esbuild's loader machinery
+      // handle resource emission.
+      if (this.#state.config.loadBundle) {
+        const { source } = this.#state.getFile(pathToFileURL(path).toString())
+        if (kind === 'resource') return { contents: source }
+        return { contents: source, loader: this.#loaderFor(path) }
+      }
+
+      const source = await realReadFile(path)
+
+      if (kind === 'resource') {
+        // Mark this file as a resource. State picks the encoding from its bytes:
+        // 'resource' (raw UTF-8 -- e.g. SVG stays human-readable in the bundle)
+        // for valid UTF-8 content, 'resource:base64' for binary. We do NOT return
+        // contents/loader: emission is esbuild's job via the build's own `loader`
+        // config (file, dataurl, copy, ...), the same way webpack's file-loader
+        // runs independently of stasis's afterResolve hook. An asset with no
+        // configured loader errors in esbuild, which
+        // is the user's responsibility (symmetric with file-loader being required).
+        if (!this.#seen.has(path)) {
+          this.#seen.add(path)
+          this.#state.addFile(pathToFileURL(path).toString(), { source, isEntry: pluginData?.isEntry, resource: true, reason: 'StasisEsbuild' })
+        }
+        return undefined
+      }
+
+      // Code-classified files must be UTF-8. A code extension with non-UTF-8 bytes
+      // is malformed input (e.g. a .json mis-saved as UTF-16); refuse it rather
+      // than silently encoding it as a resource and hiding the underlying problem.
+      assert.ok(isUtf8(source), `StasisEsbuild: code-classified file has non-UTF-8 bytes: ${path}`)
+
+      if (!this.#seen.has(path)) {
+        this.#seen.add(path)
+        this.#state.addFile(pathToFileURL(path).toString(), { source, isEntry: pluginData?.isEntry, reason: 'StasisEsbuild' })
+      }
+
+      return { contents: source, loader: this.#loaderFor(path) }
+    })
+  }
+}

package/src/metro-transformer.js

@@ -0,0 +1,125 @@
+import { Buffer } from 'node:buffer'
+import { createRequire } from 'node:module'
+import { resolve as resolvePath } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { State } from '@exodus/stasis-core/state'
+
+// Companion to the StasisMetro serializer plugin: the LOAD half of stasis for Metro.
+//
+// WHY A TRANSFORMER (the asymmetry that makes this possible):
+//   Capture must MERGE every worker's observations into one lockfile/bundle, so it
+//   runs in the main process (the serializer -- see metro.js). Load is the opposite:
+//   it only ever READS an immutable bundle, and every worker reads the SAME bytes, so
+//   there is nothing to synchronize between them. That makes the per-worker transformer
+//   the natural seam for load -- each worker independently serves attested bytes, no IPC.
+//
+// HOW IT WIRES IN (metro.config.js, load mode only):
+//   module.exports = {
+//     transformer: {
+//       transformerPath: require.resolve('@exodus/stasis/metro-transformer'),
+//     },
+//   }
+//   // run with EXODUS_STASIS_BUNDLE=load (+ EXODUS_STASIS_BUNDLE_FILE / LOCK / SCOPE),
+//   // OR a stasis.config.json with "bundle":"load". Do NOT also wire the StasisMetro
+//   // serializer plugin in load mode -- capture and load are separate wirings.
+//
+//   Metro calls `transformerPath`'s `transform(config, projectRoot, filename, data,
+//   options)` in each worker with `data` = the file's on-disk bytes (a Buffer) and
+//   `filename` project-relative. We wrap the user's real transformer (default
+//   `metro-transform-worker`, override via EXODUS_STASIS_METRO_BASE_TRANSFORMER) and,
+//   in load mode, replace `data` with the bundle's attested bytes before delegating --
+//   so the transform consumes bundle bytes, hash-verified, fail-closed.
+//
+// WHAT THIS DOES AND DOESN'T GUARANTEE:
+//   - The bytes that get TRANSFORMED are the bundle's, verified by State.getFile
+//     (against the lockfile when one is loaded; against the bundle's own bytes under
+//     lock=none). A tampered on-disk source is therefore ignored for the build output
+//     and, under a lockfile, rejected outright. An in-scope file the bundle doesn't
+//     carry throws -- never a silent disk fallback. Out-of-scope files pass their disk
+//     bytes through untouched (mirrors webpack/esbuild load scope handling).
+//   - KNOWN LIMITATION: this does NOT let Metro build with the sources fully absent
+//     from disk. Metro reads each file from disk in the worker (and hashes it in the
+//     main process for its transform cache) BEFORE this transformer runs, and resolves
+//     package.json via its own fs in the main process. Serving those reads from the
+//     bundle would need fs interception across the main + worker processes (stasis
+//     --mock territory), which is larger than this seam. So today's guarantee is
+//     "build the bundle's attested bytes, fail closed on disk drift," not "build from
+//     a bundle with no source tree." This mirrors the documented node_modules-crossing
+//     gap in the webpack load path.
+
+const require = createRequire(import.meta.url)
+
+// The real transformer we wrap. Default matches Metro's default; an app with a custom
+// transformer (e.g. a TS/Babel preset) points this at theirs so we sit transparently
+// in front of it. Resolved + required lazily (per worker process) so a non-load build
+// pays nothing and we don't require Metro internals at import time.
+const BASE_TRANSFORMER = process.env.EXODUS_STASIS_METRO_BASE_TRANSFORMER || 'metro-transform-worker'
+
+let base
+function getBase() {
+  base ??= require(BASE_TRANSFORMER)
+  return base
+}
+
+// Per-worker load State, built once. We construct a normal State (it reads the same
+// EXODUS_STASIS_* env + stasis.config.json the rest of stasis does) and only act when
+// it resolves to load mode; any other mode -> null -> this transformer is a transparent
+// pass-through, so wiring it permanently in metro.config.js is safe.
+let stateInited = false
+let loadState = null
+function getLoadState() {
+  if (!stateInited) {
+    stateInited = true
+    const state = new State(process.cwd())
+    loadState = state.config.loadBundle ? state : null
+  }
+  return loadState
+}
+
+// True iff `absolute` is a path the bundle is supposed to cover under load mode.
+// `state.relative` throws for paths outside the project root, which we treat as
+// out-of-scope (system files, scratch dirs) and defer to disk. Mirrors the webpack
+// plugin's load-mode inScope.
+function inScope(state, absolute) {
+  try {
+    state.relative(absolute)
+  } catch {
+    return false
+  }
+  if (state.config.full) return true
+  return state.inNodeModules(pathToFileURL(absolute).toString())
+}
+
+export function transform(config, projectRoot, filename, data, options) {
+  const state = getLoadState()
+  if (state) {
+    // `filename` is project-relative in Metro's transformer contract; resolve against
+    // projectRoot (resolvePath ignores projectRoot when filename is already absolute).
+    const absolute = resolvePath(projectRoot, filename)
+    if (inScope(state, absolute)) {
+      // getFile re-verifies the hash against the lockfile on every read and throws on a
+      // file the bundle doesn't carry -- so an in-scope path the bundle is missing
+      // surfaces here as a hard build error, not a silent disk fallback. Code sources
+      // come back as strings; resources as Buffers (already decoded from base64).
+      const { source } = state.getFile(pathToFileURL(absolute).toString())
+      data = Buffer.isBuffer(source) ? source : Buffer.from(source)
+    }
+  }
+  return getBase().transform(config, projectRoot, filename, data, options)
+}
+
+export function getCacheKey(config) {
+  // Fold the wrapped transformer's own cache key in (so changing the base transformer
+  // still invalidates), then add a stasis-load discriminator: load-mode transforms can
+  // produce different bytes than a disk build for the same file (and Metro hashes the
+  // on-disk bytes into its cache key BEFORE we substitute, so when disk == bundle the
+  // content hash alone wouldn't tell a load result apart from a plain build), so their
+  // cached results must not cross-pollinate. Derive the marker from the resolved load
+  // State -- the SAME source of truth as transform() -- not the env var, so load activated
+  // via stasis.config.json is keyed correctly too; the bundle path keys it to the bundle.
+  const baseKey = typeof getBase().getCacheKey === 'function' ? getBase().getCacheKey(config) : ''
+  const state = getLoadState()
+  const marker = state ? `load:${state.config.bundleFile || 'default'}` : 'off'
+  return `${baseKey}$stasis-metro-transformer:${marker}`
+}