refactor(kernel-utils): replace vat bundler NODE_ENV define with a plugin (#967)

## Summary

Moves `process.env.NODE_ENV` injection out of the `bundleVat` build
config and into a dedicated, auto-detecting Rolldown transform plugin,
resolving #812.

Previously `bundleVat` configured a Vite `define` that textually
substituted `process.env.NODE_ENV` → `"production"` on every build. It
was a workaround for libraries (e.g. immer) that branch on
`process.env.NODE_ENV`, but baking it into the build config coupled
bundling to an env-shimming concern. The new `replaceNodeEnvPlugin`
makes that logic a first-class, unit-tested plugin instead.

## Changes

- **New `replaceNodeEnvPlugin`**
(`packages/kernel-utils/src/vite-plugins/replace-node-env-plugin.ts`) —
a Rolldown `transform` plugin that inlines `process.env.NODE_ENV` as a
string literal in any module referencing it, and no-ops otherwise.
Mirrors the sibling `removeDynamicImportsPlugin`.
- **Configurable value** — the plugin accepts an options bag `{ value }`
(type `ReplaceNodeEnvPluginOptions`), defaulting to `'production'`, so
callers can inline a different `process.env.NODE_ENV` value.
- **`bundle-vat.ts`** — removed the `define` block (and its TODO) and
added `replaceNodeEnvPlugin()` to the `rolldownOptions.plugins` array
(uses the `'production'` default).
- **`index.ts`** — exports the new plugin and its options type alongside
`removeDynamicImportsPlugin`.
- **Tests** — `replace-node-env-plugin.test.ts` covers positive/negative
cases, the quoted-literal assertion, the word-boundary near-miss
(`NODE_ENVIRONMENT`), and a configured non-default value.

## Behavior

For the default value, output is identical to the old `define` for any
bundle referencing `process.env.NODE_ENV` — the logic is just relocated
to a named, tested plugin.

## Verification

- `yarn workspace @metamask/kernel-utils build` — passes.
- `yarn workspace @metamask/kernel-utils test:dev:quiet` — passes (new +
existing plugin/index tests).
- End-to-end: bundling a fixture that reads `process.env.NODE_ENV`
produced `var isProd = true; var rawMode = "production";` — fully
inlined and constant-folded, no residual `process.env.NODE_ENV`
reference.
- `yarn lint` — clean.

Closes #812

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Build-time bundling refactor with equivalent default behavior; limited
to kernel-utils vat bundling and covered by new tests.
> 
> **Overview**
> **`bundleVat`** no longer sets a global Vite `define` for
`process.env.NODE_ENV`. That injection is handled by a new Rolldown
**`replaceNodeEnvPlugin`**, wired into the vat bundle pipeline alongside
the existing dynamic-import stripper.
> 
> The plugin only transforms modules that reference
`process.env.NODE_ENV`, replacing them with a JSON-stringified literal
(default **`"production"`**, overridable via `{ value }`). That keeps
vat bundles safe for deps like immer when there is no runtime `process`
global, without coupling every build to a blanket define.
> 
> **`replaceNodeEnvPlugin`** and **`ReplaceNodeEnvPluginOptions`** are
exported from **`./vite-plugins`**, with unit tests covering
replacements, no-ops, word boundaries, and custom values. CHANGELOG
documents the addition.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
8f73140. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: rekmarks

packages/kernel-utils/CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add an optional `required` field to `MethodSchema` (mirroring `required` on object `JsonSchema`) naming which arguments are required, and a `{ required }` option on `methodArgsToStruct` that validates unlisted arguments as optional, so a method's argument schema can faithfully represent the optional trailing arguments its guard already allows ([#958](https://github.com/MetaMask/ocap-kernel/pull/958))
 - Add `getLibp2pRelayHome()` to the `./nodejs` exports, returning the libp2p relay's bookkeeping directory (default `~/.libp2p-relay`, overridable via `$LIBP2P_RELAY_HOME`) — kept separate from `$OCAP_HOME` so one relay can serve daemons with different OCAP_HOMEs ([#952](https://github.com/MetaMask/ocap-kernel/pull/952))
 - `startRelay()` accepts an optional `publicIp` that is fed to libp2p's `appendAnnounce`, so a relay running on a NAT-backed host can announce its publicly-reachable IPv4 alongside its bound NIC addresses ([#952](https://github.com/MetaMask/ocap-kernel/pull/952))
+- Add `replaceNodeEnvPlugin` to the `./vite-plugins` exports, a Rolldown transform plugin that inlines `process.env.NODE_ENV` as a string literal (configurable via `{ value }`, defaulting to `'production'`) in any module referencing it — used by `bundleVat` in place of a build-config `define`, so vats that pull in libraries like immer resolve the reference at bundle time ([#967](https://github.com/MetaMask/ocap-kernel/pull/967))
 
 ## [0.5.0]
 

packages/kernel-utils/src/vite-plugins/bundle-vat.ts

@@ -7,6 +7,7 @@ import { build } from 'vite';
 
 import type { VatBundle } from '../vat-bundle.ts';
 import { exportMetadataPlugin } from './export-metadata-plugin.ts';
+import { replaceNodeEnvPlugin } from './replace-node-env-plugin.ts';
 import { stripCommentsPlugin } from './strip-comments-plugin.ts';
 
 export type { VatBundle } from '../vat-bundle.ts';
@@ -88,12 +89,6 @@ export async function bundleVat(sourcePath: string): Promise<VatBundle> {
     result = await build({
       configFile: false,
       logLevel: 'silent',
-      // TODO: Remove this define block and add a process shim to VatSupervisor
-      // workerEndowments instead. This injects into ALL bundles but is only needed
-      // for libraries like immer that check process.env.NODE_ENV.
-      define: {
-        'process.env.NODE_ENV': JSON.stringify('production'),
-      },
       build: {
         write: false,
         minify: false,
@@ -109,6 +104,7 @@ export async function bundleVat(sourcePath: string): Promise<VatBundle> {
           },
           plugins: [
             removeDynamicImportsPlugin(),
+            replaceNodeEnvPlugin(),
             stripCommentsPlugin(),
             metadataPlugin,
           ],

packages/kernel-utils/src/vite-plugins/index.ts

@@ -4,6 +4,8 @@ import { bundleVat } from './bundle-vat.ts';
 
 export { bundleVat, removeDynamicImportsPlugin } from './bundle-vat.ts';
 export type { VatBundle } from './bundle-vat.ts';
+export { replaceNodeEnvPlugin } from './replace-node-env-plugin.ts';
+export type { ReplaceNodeEnvPluginOptions } from './replace-node-env-plugin.ts';
 
 type VatEntry = {
   /** Absolute path to the vat source file */

packages/kernel-utils/src/vite-plugins/replace-node-env-plugin.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+
+import { replaceNodeEnvPlugin } from './replace-node-env-plugin.ts';
+
+type TransformFn = (
+  code: string,
+  id: string,
+) => { code: string; map: null } | null;
+
+describe('replaceNodeEnvPlugin', () => {
+  const plugin = replaceNodeEnvPlugin();
+  const transform = plugin.transform as TransformFn;
+
+  it.each([
+    ['bare reference', `process.env.NODE_ENV`, `"production"`],
+    [
+      'reference in a conditional',
+      `if (process.env.NODE_ENV !== 'production') { warn(); }`,
+      `if ("production" !== 'production') { warn(); }`,
+    ],
+    [
+      'multiple references in one file',
+      `const a = process.env.NODE_ENV;\nconst b = process.env.NODE_ENV;`,
+      `const a = "production";\nconst b = "production";`,
+    ],
+    [
+      'reference surrounded by other code',
+      `const x = 1;\nexport const mode = process.env.NODE_ENV;\nconst y = 2;`,
+      `const x = 1;\nexport const mode = "production";\nconst y = 2;`,
+    ],
+  ])(
+    'replaces %s with the "production" string literal',
+    (_name, code, expected) => {
+      const result = transform(code, 'test.ts');
+      expect(result).toStrictEqual({ code: expected, map: null });
+    },
+  );
+
+  it('injects a quoted string literal, not the bare word', () => {
+    const result = transform(`const mode = process.env.NODE_ENV;`, 'test.ts');
+    expect(result?.code).toContain(`"production"`);
+    expect(result?.code).not.toContain(`process.env.NODE_ENV`);
+    expect(result?.code).not.toContain(`= production;`);
+  });
+
+  it.each([
+    ['no process reference', 'const x = 1;'],
+    ['unrelated process.env key', `const port = process.env.PORT;`],
+    ['empty code', ''],
+  ])('returns null for %s', (_name, code) => {
+    expect(transform(code, 'test.ts')).toBeNull();
+  });
+
+  it('returns null when the substring matches but the word boundary does not', () => {
+    const code = `const x = process.env.NODE_ENVIRONMENT;`;
+    expect(transform(code, 'test.ts')).toBeNull();
+  });
+
+  it('inlines a configured value instead of the default', () => {
+    const devTransform = replaceNodeEnvPlugin({ value: 'development' })
+      .transform as TransformFn;
+    const result = devTransform(
+      `const mode = process.env.NODE_ENV;`,
+      'test.ts',
+    );
+    expect(result).toStrictEqual({
+      code: `const mode = "development";`,
+      map: null,
+    });
+  });
+});

packages/kernel-utils/src/vite-plugins/replace-node-env-plugin.ts

@@ -0,0 +1,51 @@
+import type { Plugin as RolldownPlugin } from 'rolldown';
+
+export type ReplaceNodeEnvPluginOptions = {
+  /**
+   * The value to inline for `process.env.NODE_ENV`. Defaults to `'production'`.
+   */
+  value?: string;
+};
+
+/**
+ * A Rolldown plugin that inlines `process.env.NODE_ENV` as a string literal in
+ * any module that references it.
+ *
+ * This replaces the former build-config `define` (issue #812). Libraries such
+ * as immer branch on `process.env.NODE_ENV`, and vats have no `process` global
+ * at runtime, so the reference must be resolved at bundle time. The plugin
+ * auto-detects the need: modules without the reference are left untouched.
+ *
+ * This is a textual replacement (the same class of approach as the sibling
+ * {@link removeDynamicImportsPlugin}) and handles the dotted
+ * `process.env.NODE_ENV` form, consistent with the `define` it replaces.
+ *
+ * @param options - Plugin options.
+ * @param options.value - The value to inline for `process.env.NODE_ENV`.
+ * Defaults to `'production'`.
+ * @returns A Rolldown plugin.
+ */
+export function replaceNodeEnvPlugin({
+  value = 'production',
+}: ReplaceNodeEnvPluginOptions = {}): RolldownPlugin {
+  const replacement = JSON.stringify(value);
+  return {
+    name: 'ocap-kernel:replace-node-env',
+    transform(code) {
+      if (!code.includes('process.env.NODE_ENV')) {
+        return null;
+      }
+
+      const transformed = code.replace(
+        /\bprocess\.env\.NODE_ENV\b/gu,
+        replacement,
+      );
+
+      if (transformed === code) {
+        return null;
+      }
+
+      return { code: transformed, map: null };
+    },
+  };
+}