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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/stasis-plugins",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.1",
   "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.0"
+    "@exodus/stasis-core": "1.0.0-beta.1"
   }
 }

package/src/esbuild.js

@@ -21,6 +21,11 @@ export class StasisEsbuild {
   #resources
   #loaders
 
+  // Build starts observed by this (capture-mode) instance, across rebuilds AND across separate
+  // esbuild.build()/context() calls sharing one instance. The second start is refused -- see
+  // the onStart hook in setup().
+  #captureBuildCount = 0
+
   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
@@ -49,9 +54,33 @@ export class StasisEsbuild {
     return 'stasis'
   }
 
-  setup = ({ onResolve, onLoad, onEnd, resolve }) => {
+  setup = ({ onResolve, onLoad, onStart, onEnd, resolve }) => {
     if (!this.#state) return  // noop plugin
 
+    // Watch/rebuild capture is EXPLICITLY UNSUPPORTED -- fail the second build 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 file's bytes changed the
+    // plugin would skip re-capture: the emitted output would use the new bytes while the
+    // bundle/lockfile silently kept attesting the OLD ones. Rather than track content changes
+    // across rebuilds, refuse them outright. esbuild rebuilds (watch mode, context.rebuild())
+    // re-fire onStart/onEnd against the SAME setup registrations, so an instance-level counter
+    // sees every start; it also covers reusing one plugin instance across two esbuild.build()
+    // calls, which has the same staleness hazard. Returning errors from onStart is the
+    // esbuild-idiomatic hard failure (the build reports them and onEnd's clean-build gate then
+    // skips the write). Load mode registers nothing here: it serves immutable attested bytes,
+    // so rebuilds have no drift hazard.
+    if (!this.#state.config.loadBundle) {
+      onStart(() => {
+        this.#captureBuildCount += 1
+        if (this.#captureBuildCount === 1) return undefined
+        return {
+          errors: [{
+            text: 'StasisEsbuild: watch/rebuild is not supported for capture -- run a one-shot build (rebuilds would silently attest stale content)',
+          }],
+        }
+      })
+    }
+
     // 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

package/src/metro.js

@@ -108,13 +108,19 @@ function metroDefaultSerializer() {
 //   hook) is a lower-coverage fallback -- see its note.
 //
 // KNOWN LIMITATIONS (Metro-specific coverage gaps -- documented, not silently ignored):
-//   - Child-process capture is best-effort and one-shot-build only. A worker KILLED by signal
+//   - 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: a dev server (`metro start`,
-//     pool kept warm, killed by signal) never gets there, and standalone (no stasis loader) Metro
-//     mints no shard dir -- neither produces a toolchain-complete lockfile. Use a one-shot
-//     `metro build` under `stasis run --child-process` to capture, then verify with `--lock=frozen`.
+//     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
+//     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
 //     scales/files arrays), NOT as separate graph modules, so only the base file is attested
@@ -130,6 +136,11 @@ export class StasisMetro {
   #state
   #resources
 
+  // 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.
+  #ran = false
+
   constructor(options = {}) {
     const { state } = resolvePluginState('StasisMetro', options, process.cwd())
     this.#state = state // null when the plugin should be inert (Rule 7)
@@ -192,15 +203,31 @@ export class StasisMetro {
         'serializer config in load mode, or use bundle=add/replace/frozen here to capture.'
       )
     }
+    // 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
+    // file's bytes changed the plugin would skip re-capture: the emitted bundle would use the
+    // new bytes while the stasis bundle/lockfile silently kept attesting the OLD ones. The
+    // 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.)
+    if (this.#ran) {
+      throw new Error(
+        'StasisMetro: watch/dev-server rebuilds are not supported for capture -- use a one-shot `metro build`'
+      )
+    }
+    this.#ran = true
     this.#capture(graph, preModules)
 
     // 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 here. The
     // serializer only runs once Metro has successfully built + transformed the whole graph
     // (a failed build throws before serialization), so this is the clean-build equivalent of
-    // webpack's `stats.hasErrors()` / esbuild's `result.errors.length` gate. In watch / dev
-    // mode it fires on every rebuild; State.write's per-artifact compare-and-skip makes the
-    // unchanged-graph case a cheap no-op.
+    // webpack's `stats.hasErrors()` / esbuild's `result.errors.length` gate -- and it runs at
+    // most once per instance (the rebuild guard above), so this write is the one-shot build's
+    // single flush.
     if (this.#state !== State.preload) this.#state.write()
   }
 

package/src/webpack.js

@@ -484,35 +484,45 @@ export class StasisWebpack {
       })
     })
 
+    // Watch-mode capture is EXPLICITLY UNSUPPORTED -- refuse it loudly before anything is
+    // captured. Capture's dedupe is keyed by PATH, not content (#seen above, plus State.write's
+    // compare-and-skip caches), so on a watch rebuild where a file's bytes changed the plugin
+    // would skip re-capture: the emitted output would use the new bytes while the bundle /
+    // lockfile silently kept attesting the OLD ones. Rather than track content changes across
+    // rebuilds, refuse watch outright. compiler.hooks.watchRun fires ONLY under
+    // compiler.watch() (both webpack 4 and 5) and BEFORE the first watch build's compilation,
+    // so this rejects the whole watch session up front, not just the second build. watchRun is
+    // an AsyncSeriesHook: a sync `.tap` callback that throws propagates through the hook's call
+    // chain and fails the watcher -- exactly the loud refusal we want, so keep it a plain tap.
+    // Load mode is deliberately untouched (see #applyLoadMode): it serves immutable attested
+    // bytes back into the build, so a dev-server rebuild has no drift hazard there.
+    compiler.hooks.watchRun.tap('Stasis', () => {
+      throw new Error(
+        'StasisWebpack: watch mode is not supported for capture -- ' +
+        'run a one-shot build (watch rebuilds would silently attest stale content)'
+      )
+    })
+
     // 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
     // compiler finishes -- but only on a clean build. A failed compilation has incomplete
     // state, and lock=replace would otherwise overwrite a good lockfile with a partial one.
     if (this.#state !== State.preload) {
-      // Watch-mode detection. compiler.hooks.watchRun fires ONLY under compiler.watch() (both
-      // webpack 4 and 5) and always before that build's `done`, so the flag is set in time.
-      // The flag is per-compiler (this closure), which is what we want: each compiler reports
-      // its own run kind even when one shared plugin instance drives several.
-      let watching = false
-      compiler.hooks.watchRun.tap('Stasis', () => { watching = true })
       compiler.hooks.done.tap('Stasis', (stats) => {
         if (stats.hasErrors()) return
-        // Write immediately when the bundle cannot grow across `done`s:
-        //   - watch mode: a watcher keeps the event loop alive, so a deferred flush would never
-        //     fire; per-rebuild freshness is the point, and State.write's compare-and-skip keeps
-        //     an unchanged rebuild a ~no-op; and
-        //   - a single compiler: only one `done`, so there is no N-write amplification and no
-        //     reason to give up the old write-by-`done` durability (the bundle is on disk by the
-        //     time compiler.run()'s callback resolves).
-        // Defer ONLY the multi-compiler one-shot case. compiler.hooks.done fires once PER CHILD
-        // COMPILER, so a MultiCompiler with N targets sharing this one State's growing bundle
-        // would otherwise pay N brotli + writeFileSync passes over an ever-larger payload (the
+        // Write immediately for a single compiler: only one `done`, so there is no N-write
+        // amplification and no reason to give up the old write-by-`done` durability (the
+        // bundle is on disk by the time compiler.run()'s callback resolves). Defer ONLY the
+        // multi-compiler one-shot case. compiler.hooks.done fires once PER CHILD COMPILER, so
+        // a MultiCompiler with N targets sharing this one State's growing bundle would
+        // otherwise pay N brotli + writeFileSync passes over an ever-larger payload (the
         // dominant, super-linear cost). Deferral collapses those into ONE write of the final
-        // bundle at process exit -- mirroring how the preload writes (hooks.js). esbuild / metro
+        // bundle at process exit -- mirroring how the preload writes (hooks.js). Watch mode
+        // never reaches this hook: capture refuses it at watchRun above. esbuild / metro
         // are deliberately NOT changed: their write hook fires once per build (no per-child
         // amplification), and stasis build reads esbuild output in-process, so their synchronous
         // write is load-bearing in a way webpack's per-child `done` write is not.
-        if (watching || this.#captureApplyCount === 1) this.#state.write()
+        if (this.#captureApplyCount === 1) this.#state.write()
         else this.#deferWrite()
       })
     }
@@ -527,8 +537,9 @@ export class StasisWebpack {
   // 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 and watch (`--watch`, dev-server)
-  // flows are unaffected, and a single-compiler build never reaches here (it writes on `done`).
+  // (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).
   #deferWrite() {
     this.#deferredWriteDirty = true
     if (this.#deferredWriteArmed) return