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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/stasis-plugins",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "description": "Bundler plugins (webpack, esbuild, Metro) for @exodus/stasis-core",
   "type": "module",
   "exports": {
@@ -31,6 +31,6 @@
   },
   "homepage": "https://github.com/ExodusOSS/stasis#readme",
   "dependencies": {
-    "@exodus/stasis-core": "1.0.0-beta.1"
+    "@exodus/stasis-core": "1.0.0-beta.2"
   }
 }

package/src/metro-transformer.js

@@ -14,15 +14,16 @@ import { State } from '@exodus/stasis-core/state'
 //   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):
+// HOW IT WIRES IN (metro.config.js) -- wire it PERMANENTLY, alongside the serializer half:
 //   module.exports = {
-//     transformer: {
-//       transformerPath: require.resolve('@exodus/stasis/metro-transformer'),
-//     },
+//     transformerPath: require.resolve('@exodus/stasis/metro-transformer'),  // top-level, a sibling of `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.
+//   // OR a stasis.config.json with "bundle":"load". Outside load mode this transformer is
+//   // a transparent pass-through (see getLoadState), and under load the StasisMetro
+//   // serializer is one too -- one committed metro.config.js carries both halves, the
+//   // mode picks the active one (the config is itself attested at capture, so a load
+//   // run must execute it unedited).
 //
 //   Metro calls `transformerPath`'s `transform(config, projectRoot, filename, data,
 //   options)` in each worker with `data` = the file's on-disk bytes (a Buffer) and

package/src/metro.js

@@ -26,6 +26,26 @@ function entrySet(graph) {
   return new Set()
 }
 
+// Well-known files a React Native / Metro build REQUIRES that the serializer's module
+// graph never reliably carries -- attested automatically at capture when they resolve
+// from the project, and skipped when they don't (not every Metro project ships them):
+//   - metro-runtime/src/modules/asyncRequire.js: Metro's default
+//     `transformer.asyncRequireModulePath`. The transform injects it to implement
+//     dynamic import(), so it ships in bundles without necessarily appearing as a
+//     module of the graph handed to the serializer.
+//   - @react-native-community/cli/setup_env.sh: sourced by the React Native CLI's
+//     native build phases (Xcode / Gradle) around the JS bundle step -- build-shaping
+//     toolchain that is never part of the JS module graph at all.
+// A `resource: true` entry bypasses the `resources` allowlist: this is a stasis-vetted
+// list of SPECIFIC files, not a user-widened extension class. Code entries ride the
+// normal loader-format inference. Extend the list here, not via an option -- an option
+// would make the attested set configuration-dependent, which is exactly what
+// auto-include exists to avoid.
+const AUTO_INCLUDES = [
+  { specifier: 'metro-runtime/src/modules/asyncRequire.js', resource: false },
+  { specifier: '@react-native-community/cli/setup_env.sh', resource: true },
+]
+
 // Metro has no public "default serializer" export, but its default bundle CODE is exactly
 // `bundleToString(baseJSBundle(entryPoint, preModules, graph, options)).code` (Metro's own
 // Server.js else-branch when no customSerializer is set). bundleToString returns
@@ -86,14 +106,22 @@ function metroDefaultSerializer() {
 //   inputFileSystem wrapper, esbuild's onLoad). Metro reads + transforms in workers,
 //   before serialization, so the serializer can't inject bytes into the transform.
 //   Load is instead handled per-worker by the companion `./metro-transformer.js`
-//   (wired as Metro's `transformer.transformerPath`): unlike capture, load only ever
+//   (wired as Metro's top-level `transformerPath`): unlike capture, load only ever
 //   READS the immutable bundle and every worker reads the same bytes, so there is no
-//   cross-worker state to merge. This serializer therefore REJECTS bundle=load.
-//   Capture modes (lock/bundle add|replace|frozen, and lock=none/ignore) all work.
+//   cross-worker state to merge. Under bundle=load this serializer is therefore a
+//   transparent PASS-THROUGH (captures nothing, writes nothing, delegates to the
+//   base serializer), mirroring the transformer, which passes through in every
+//   non-load mode. Wire BOTH halves permanently; the mode picks the active one.
+//   That matters because metro.config.js is itself attested at capture, so a load
+//   run must execute it unedited. Capture modes (lock/bundle add|replace|frozen,
+//   and lock=none/ignore) all capture here.
 //
-// USAGE (metro.config.js) -- prefer withStasis:
+// USAGE (metro.config.js) -- prefer withStasis; wire the load half permanently alongside it:
 //   const { withStasis } = require('@exodus/stasis/metro')
-//   module.exports = withStasis(require('./metro.config.base'), { /* scope, lock, ... */ })
+//   module.exports = withStasis({
+//     ...require('./metro.config.base'),
+//     transformerPath: require.resolve('@exodus/stasis/metro-transformer'),  // the load half
+//   }, { /* scope, lock, ... */ })
 //
 //   Then CAPTURE with child-process forwarding ON -- Metro transforms in worker processes, so
 //   `--child-process` is REQUIRED on a capture run to attest the toolchain those workers load
@@ -107,19 +135,37 @@ function metroDefaultSerializer() {
 //   `new StasisMetro(opts).customSerializer(base?)`. `serializerHook` (the experimental
 //   hook) is a lower-coverage fallback -- see its note.
 //
+// AUTO-INCLUDED FILES: capture also attests the fixed AUTO_INCLUDES list (see it above
+//   the class) -- files a React Native build requires that the serializer's graph never
+//   reliably carries (Metro's asyncRequire module, the RN CLI's setup_env.sh). Each is
+//   attested when it resolves from the project and skipped when it doesn't, through the
+//   same addFile path as graph modules, so frozen verification covers them fail-closed.
+//   NOTE: a lockfile captured before this list existed doesn't attest these files, so a
+//   frozen run against it fails once they're present -- recapture (lock=replace) once.
+//
 // KNOWN LIMITATIONS (Metro-specific coverage gaps -- documented, not silently ignored):
 //   - Capture is ONE-SHOT ONLY, enforced: a dev server (`metro start`) re-invokes the serializer
 //     per rebuild, and the SECOND invocation throws (see #run) -- capture's path-keyed dedupe
 //     would otherwise keep attesting a file's first-build bytes after an edit changed them.
 //     Metro gives the serializer no watch signal on the first build, so the first rebuild is the
-//     earliest refusal point. Load mode (the companion worker transformer) is unaffected and
-//     runs fine under a dev server -- it only reads immutable attested bytes.
-//   - Child-process capture is best-effort within that one shot. A worker KILLED by signal
-//     before its exit hook (jest-worker forceExit / pool overflow) loses its shard SILENTLY at
-//     capture time -- a later frozen run still catches the gap (fail-closed), but nothing warns
-//     during capture. And it relies on the loader's exit-time write, which standalone (no stasis
-//     loader) Metro never reaches -- it mints no shard dir and produces no toolchain-complete
-//     lockfile. Use a one-shot `metro build` under `stasis run --child-process` to capture, then
+//     earliest refusal point. Load mode is unaffected and runs fine under a dev server --
+//     the serializer passes through and the worker transformer only reads immutable
+//     attested bytes.
+//   - Child-process capture is best-effort within that one shot. A writing plugin opts the
+//     build's workers into the loader's SIGTERM shard flush (EXODUS_STASIS_SHARD_SIGNAL_FLUSH,
+//     set in the constructor), so a worker force-killed by jest-worker's forceExit -- SIGTERM
+//     500ms after END, routine for a transform worker whose event loop doesn't drain --
+//     contributes its shard best-effort: the flush must complete inside forceExit's follow-up
+//     500ms SIGTERM->SIGKILL window. A worker killed any OTHER way still loses its shard
+//     SILENTLY at capture time -- SIGKILL (jest-worker's memory-limit killChild, a
+//     killSignal:'SIGKILL' override), a non-SIGTERM signal (group SIGINT/SIGHUP, another
+//     killSignal override; the flush handler is SIGTERM-only), or a nested orchestration's
+//     Metro MAIN process (itself a capturing child, it snapshots its config before this
+//     constructor sets the flag, so only its descendants are covered). A later frozen run
+//     catches every such gap (fail-closed), but nothing warns during capture. And it relies
+//     on the loader's exit/signal-time writes, which standalone (no stasis loader) Metro
+//     never reaches -- it mints no shard dir and produces no toolchain-complete lockfile.
+//     Use a one-shot `metro build` under `stasis run --child-process` to capture, then
 //     verify with `--lock=frozen`.
 //   - Scaled asset variants: `import x from './logo.png'` is ONE module in the graph, keyed
 //     by the base path; Metro discovers `logo@2x.png` / `@3x` via its AssetData (parallel
@@ -136,6 +182,13 @@ export class StasisMetro {
   #state
   #resources
 
+  // Base dir AUTO_INCLUDES resolution starts from: the directory Metro runs in -- the
+  // same cwd resolvePluginState anchors the State at, and an in-or-under-root path by
+  // State's own root detection (which walks UP from it), so Node's node_modules walk-up
+  // from here also covers hoisted workspace layouts. Snapshotted at construction so a
+  // later chdir can't skew what a capture attests.
+  #projectDir = process.cwd()
+
   // Whether this instance already served one capture (#run). The serializer fires once per
   // one-shot `metro build`; a dev server re-invokes it per rebuild, which capture refuses --
   // see the guard in #run.
@@ -162,6 +215,26 @@ export class StasisMetro {
         'is never attested. Enable it: `stasis run --child-process ...`, EXODUS_STASIS_CHILD_PROCESS=1, ' +
         'or "childProcess": true in stasis.config.json.'
       )
+      // Opt this build's children into the loader's SIGTERM shard flush: jest-worker's
+      // forceExit would otherwise silently drop a non-draining worker's shard (mechanics in
+      // the KNOWN LIMITATIONS bullet above; the handler lives in hooks.js). The flag rides
+      // process.env, so EVERY capturing child forked after config time inherits it --
+      // Metro's transform workers are the intended audience, but a codegen fork the build
+      // spawns rides along; the loader's own gates (child + shard forwarding) bound what it
+      // can do there to a flush-then-redeliver on SIGTERM. The plugin can't act inside the
+      // workers (only the loader runs there), so an env opt-in is the seam; scoped HERE,
+      // not globally, because changing a child's default-kill disposition is otherwise the
+      // user's domain. Two deliberate softenings:
+      //   - keyed on the PRELOAD where one exists: the shard channel is minted by, and the
+      //     children's capture mode follows, the preload's config -- a Rule-6 sidecar's own
+      //     bundle mode says nothing about either, and setting the flag under a frozen
+      //     preload would claim an opt-in that can never engage;
+      //   - `||=`, not `=`: an explicit ambient opt-out ('0'/'false', envBool's disable
+      //     values) is the user's call and is honored; only unset/empty is claimed.
+      const channel = State.preload ?? state
+      if (channel.config.writeLockfile || channel.config.writeBundle) {
+        process.env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH ||= '1'
+      }
     }
     // resources is a Config field now (validated + coordinated against any preload in
     // resolvePluginState); cache the resolved Set for the per-file classify hot path.
@@ -195,14 +268,11 @@ export class StasisMetro {
 
   #run(graph, preModules) {
     if (!this.#state) return
-    if (this.#state.config.loadBundle) {
-      throw new Error(
-        'StasisMetro: bundle=load is served by the companion worker transformer ' +
-        "(transformer.transformerPath = '@exodus/stasis/metro-transformer'), not this serializer " +
-        'plugin -- Metro transforms in workers before serialization. Remove this plugin from your ' +
-        'serializer config in load mode, or use bundle=add/replace/frozen here to capture.'
-      )
-    }
+    // bundle=load: pass through -- load is served by the companion worker transformer, and
+    // metro.config.js is itself attested at capture, so the same wiring must run unedited
+    // in load mode (see the class note). Checked BEFORE the one-shot guard: load captures
+    // nothing and legitimately re-serializes per rebuild under a dev server.
+    if (this.#state.config.loadBundle) return
     // Watch/dev-server capture is EXPLICITLY UNSUPPORTED -- refuse the second serialization
     // loudly before it captures anything. Capture's dedupe is keyed by PATH, not content
     // (#seen below, plus State.write's compare-and-skip caches), so on a rebuild where a
@@ -211,8 +281,8 @@ export class StasisMetro {
     // serializer fires exactly once per one-shot `metro build`; only a dev server
     // (`metro start`) re-invokes it, and Metro hands the serializer no watch-mode signal on
     // the FIRST build, so the first rebuild is the earliest point capture can refuse. (Load
-    // mode has no such hazard and legitimately runs under a dev server -- it lives in the
-    // companion worker transformer, rejected above, which only READS immutable attested bytes.)
+    // mode has no such hazard and legitimately runs under a dev server -- it passed through
+    // above, and the companion worker transformer only READS immutable attested bytes.)
     if (this.#ran) {
       throw new Error(
         'StasisMetro: watch/dev-server rebuilds are not supported for capture -- use a one-shot `metro build`'
@@ -239,6 +309,42 @@ export class StasisMetro {
     // app module graph.
     if (preModules) this.#captureModules(preModules, entries)
     this.#captureModules(graph.dependencies.values(), entries)
+    // AFTER the graph so #seen already holds every graph module: an auto-include that
+    // did land in the graph this build (asyncRequire does when the app uses dynamic
+    // import()) is deduped instead of re-recorded.
+    this.#captureAutoIncludes()
+  }
+
+  // Attest the AUTO_INCLUDES list (see its note above). Skips, per entry: a specifier
+  // that doesn't resolve from the project (the file genuinely doesn't exist there --
+  // nothing to attest), a file already captured as a graph module this build, and a
+  // resolution landing outside the project root (unattestable -- lockfile/bundle keys
+  // are root-relative; same out-of-scope stance as the load transformer's inScope).
+  // Everything that IS attested goes through the exact addFile path graph modules use,
+  // so frozen runs verify these files fail-closed like any other capture.
+  #captureAutoIncludes() {
+    for (const { specifier, resource } of AUTO_INCLUDES) {
+      let modPath
+      try {
+        modPath = require.resolve(specifier, { paths: [this.#projectDir] })
+      } catch {
+        continue // not installed in this project -- nothing to attest
+      }
+      if (this.#seen.has(modPath)) continue
+      try {
+        this.#state.relative(modPath)
+      } catch {
+        continue // outside the project root -- unattestable
+      }
+      this.#seen.add(modPath)
+      // Real reader for the same reason as #captureModules: this is plugin bookkeeping,
+      // not a program fs read -- it must not be re-recorded by a --fs patched reader.
+      const source = realReadFileSync(modPath)
+      if (!resource) {
+        assert.ok(isUtf8(source), `StasisMetro: code-classified file has non-UTF-8 bytes: ${modPath}`)
+      }
+      this.#state.addFile(pathToFileURL(modPath).toString(), { source, resource, reason: 'StasisMetro' })
+    }
   }
 
   #captureModules(modules, entries) {

package/src/plugins.js

@@ -163,6 +163,8 @@ export function resolvePluginState(label, options, cwd) {
       debug: pc.debug,
       childProcess: pc.childProcess,
       resources: [...pc.resources],
+      // carried over: sidecars skip stasis.config.json discovery, which may have set it
+      brotliQuality: pc.brotliQuality,
     })
     return { state: sidecar, isNoop: false }
   }
@@ -199,6 +201,7 @@ export function resolvePluginState(label, options, cwd) {
     debug: pc.debug,
     childProcess: pc.childProcess,
     resources: [...pc.resources],
+    brotliQuality: pc.brotliQuality, // carried over, like the Rule 6 sidecar above
   })
   return { state: sidecar, isNoop: false }
 }

package/src/webpack.js

@@ -536,10 +536,14 @@ export class StasisWebpack {
   // KNOWN LIMITATION: the flush runs at process exit, so a multi-compiler one-shot build inside
   // a process that never exits normally -- one that stays alive after building and is then
   // killed by a signal (SIGINT/SIGTERM/SIGKILL), which bypass both beforeExit and exit -- would
-  // not flush. That is the same capture-then-exit assumption the preload already relies on
-  // (hooks.js) and metro documents; the common build-and-exit flow is unaffected, a
-  // single-compiler build never reaches here (it writes on `done`), and watch (`--watch`,
-  // dev-server) capture is refused outright at watchRun (see #applyCaptureMode).
+  // not flush. That is the same capture-then-exit assumption the preload's ROOT write relies
+  // on (hooks.js). NB: the SIGTERM shard flush metro opts its workers into
+  // (EXODUS_STASIS_SHARD_SIGNAL_FLUSH, hooks.js) does NOT help here and setting it wouldn't
+  // either -- it covers a capturing CHILD's shard forward, while this deferred write is the
+  // MAIN process's State.write via THIS plugin's own beforeExit/exit listeners, which a signal
+  // death (or the loader's re-delivered SIGTERM) still bypasses. The common build-and-exit
+  // flow is unaffected, a single-compiler build never reaches here (it writes on `done`), and
+  // watch (`--watch`, dev-server) capture is refused outright at watchRun (see #applyCaptureMode).
   #deferWrite() {
     this.#deferredWriteDirty = true
     if (this.#deferredWriteArmed) return