use plugin for client env file and save more time plus update docs and tests

Author: jjpaulino

BUNDLER-COMPARISON.md

@@ -372,7 +372,7 @@ Vite was chosen specifically because it is the default integration point for:
 | Browserify + Gulp | 30–60 s | 90–120 s |
 | esbuild | ~3 s | ~33 s |
 | Rollup + esbuild | ~40 s | ~70 s |
-| **Vite** | **~30 s** | **~60 s** |
+| **Vite** | **~30 s** | **~30 s** (client-env now free via Rollup plugin) |
 
 Vite is faster than bare Rollup because its `optimizeDeps` pass converts `node_modules`
 CJS to ESM before Rollup sees them, reducing the number of modules `@rollup/plugin-commonjs`

CLAY-VITE.md

@@ -20,6 +20,7 @@
 8. [Code References](#8-code-references)
    - [Why `_globals-init.js` exists as a separate file](#why-_globals-initjs-exists-as-a-separate-file)
    - [Why the build runs in two passes](#why-the-build-runs-in-two-passes)
+   - [How client-env.json is generated](#how-client-envjson-is-generated)
 9. [Performance](#9-performance)
 10. [Learning Curve](#10-learning-curve)
 11. [For Product Managers](#11-for-product-managers)
@@ -168,8 +169,8 @@ clay vite
 ├── media.js    ← fs-extra copy
 │   └── components/**/media/* → public/media/
 │
-└── client-env.json ← generated by generateClientEnv()
-    └── scans source files for process.env.VAR references → client-env.json
+└── client-env.json ← generated by viteClientEnvPlugin (createClientEnvCollector)
+    └── collected as a side-effect of the Rollup transform pass — no extra file I/O
         (required by amphora-html's addEnvVars() at render time)
 ```
 
@@ -621,7 +622,7 @@ RUN if [ "$CLAYCLI_VITE_ENABLED" = "true" ]; then \
 | `.clay/vite-bootstrap.js` | `generate-bootstrap.js` | Imports every `client.js`; mounts via dynamic `import()` on DOM presence |
 | `.clay/_kiln-edit-init.js` | `generate-kiln-edit.js` | Imports every `model.js` + `kiln.js`; registers on `window.kiln.componentModels` |
 | `.clay/_globals-init.js` | `generate-globals-init.js` | Imports all `global/js/*.js` into one non-splitting entry |
-| `client-env.json` | `generateClientEnv()` | JSON array of `process.env.VAR_NAME` identifiers for `amphora-html` |
+| `client-env.json` | `createClientEnvCollector` (Rollup plugin) | JSON array of `process.env.VAR_NAME` identifiers for `amphora-html` |
 
 > **Why `.clay/` exists — and why the old pipeline didn't need it**
 >
@@ -754,6 +755,68 @@ final state after full ESM migration.
 
 ---
 
+### How client-env.json is generated
+
+`client-env.json` is a JSON array of `process.env.VAR_NAME` identifiers that `amphora-html`
+reads at server startup. For every name in the array, `amphora-html` injects
+`window.process.env.VAR = process.env.VAR` into the rendered page so that browser code
+can read it at runtime.
+
+#### The old way — grep scan (~30 seconds)
+
+The previous implementation (`generateClientEnv`) ran a full file-system scan on every
+build: glob-expand every `.js` and `.vue` file under `components/`, `layouts/`, `services/`,
+`global/`, and `amphora/`, then `fs.readFile` each one sequentially, regex-match for
+`process\.env\.([A-Z_][A-Z0-9_]*)`, and write the result.
+
+Two problems:
+1. **Speed** — O(N files), sequential I/O, ~30s standalone step on top of an already
+   30-second JS build.
+2. **Scope** — it scanned *all* source files, including server-only utilities and
+   `model.js` hooks that call external APIs.  Server secrets like `STRIPE_API_SECRET`
+   ended up in `client-env.json` even though no browser code ever reads them, creating
+   unnecessary exposure in edit mode via `window.process.env`.
+
+#### The new way — Rollup transform hook (effectively free)
+
+`createClientEnvCollector` in `lib/cmd/vite/plugins/client-env.js` returns a pair:
+
+- **`plugin()`** — a Rollup plugin whose `transform` hook scans each module as Rollup
+  already processes it.  No extra file I/O — the source is already in memory.
+- **`write()`** — flushes the accumulated Set to `client-env.json` after all passes complete.
+
+Both the view pass and the kiln pass receive their own plugin instance from the same
+collector, so a single `write()` call covers `process.env` references from both
+`client.js` files and `model.js`/`kiln.js` files.
+
+The scope boundary is now the Rollup module graph: only files that are actually imported
+(directly or transitively) by `vite-bootstrap.js` or `_kiln-edit-init.js` contribute to
+`client-env.json`.  Pure server-side utilities outside the graph — amphora route handlers,
+`services/server/*` — are never seen by Rollup and are therefore never included, which
+is exactly the right behavior.
+
+```
+Browserify pipeline:                  Vite pipeline:
+  grep all *.js + *.vue ───► 30s        Rollup transform hook ──► ~0s
+  (sequential, N files)                 (already traversing graph)
+  includes server-only files            only files in module graph
+  may expose server secrets             scope-bounded to browser surface
+```
+
+#### Watch mode behavior
+
+In watch mode, the collector is created once for the entire session.  After every
+incremental rebuild (`BUNDLE_END`), `write()` is called again with whatever is in the Set.
+Because Rollup re-transforms any changed module, a newly added `process.env.MY_VAR`
+reference is picked up automatically on the next rebuild.
+
+The Set is intentionally **append-only** within a session — removing a reference leaves a
+stale entry until the next full build.  This is the safe default: a stale extra entry
+causes the server to inject `undefined` (harmless), while a missing entry silently breaks
+client-side code.
+
+---
+
 ### Sticky events and the `stickyEvents` config key
 
 #### The problem — ESM dynamic-import race condition
@@ -813,7 +876,9 @@ The watch implementation uses **Rollup watch mode** for JS incremental rebuilds
 - **JS rebuild:** Rollup reprocesses only changed modules and their dependents
 - **Bootstrap regeneration:** when a new `client.js` is added, the bootstrap is regenerated
   automatically so the new component appears in the next rebuild
-- **client-env.json regeneration:** any JS file change triggers a `generateClientEnv()` pass
+- **client-env.json regeneration:** the `clay-client-env` Rollup plugin automatically
+  collects any new `process.env.VAR` reference as Rollup re-transforms the changed
+  module — no separate file scan, no extra I/O step
   to keep `process.env` variable references in sync
 - **usePolling: true** — required for Docker + macOS volume mounts where inotify is unreliable
 

lib/cmd/vite/plugins/client-env.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const fs = require('fs-extra');
+
+const ENV_VAR_RE = /process\.env\.([A-Z_][A-Z0-9_]*)/g;
+
+/**
+ * Factory for a shared process.env reference collector used across Rollup
+ * build passes.
+ *
+ * ── Why this replaces the grep-based scan ───────────────────────────────────
+ *
+ * The previous approach (generateClientEnv) scanned the entire source tree
+ * with a sequential fs.readFile loop on every build — O(N files), ~30s.
+ * That scan also had no awareness of the module graph: it picked up
+ * process.env references from server-only files (services/server/*, model.js
+ * save hooks that call external APIs) and added them to client-env.json,
+ * potentially leaking server secrets into the browser's window.process.env.
+ *
+ * With Vite + Rollup we already traverse every module in the graph during the
+ * transform phase.  Collecting process.env references there adds only a regex
+ * match to work Rollup is already doing — effectively free.
+ *
+ * ── Scope boundary (intentional) ────────────────────────────────────────────
+ *
+ * Only files that Rollup actually processes end up in the collected Set.
+ * Files outside the module graph (pure server utilities, amphora route handlers,
+ * anything not imported by vite-bootstrap.js or vite-kiln-edit-init.js) are
+ * intentionally excluded.  Their process.env references are native Node.js
+ * reads and should never be forwarded to the browser.
+ *
+ * ── Why both passes share one collector ─────────────────────────────────────
+ *
+ * The Vite pipeline runs two Rollup passes:
+ *   Pass 1 (view)  — client.js + global/js files for public pages.
+ *   Pass 2 (kiln)  — model.js + kiln.js for edit-mode saves in the browser.
+ *
+ * Both passes can reference process.env variables needed in the browser.
+ * Sharing a single Set across both plugin instances ensures client-env.json
+ * covers the full browser surface area in a single write.
+ *
+ * ── Watch mode note ──────────────────────────────────────────────────────────
+ *
+ * The collector's Set is append-only within a watch session.  If a developer
+ * removes a process.env reference, the var stays in the Set until the next
+ * full build.  This is intentional: stale entries in client-env.json are
+ * harmless (the server injects undefined for missing vars), while a missing
+ * entry silently breaks client-side code.
+ *
+ * @param {string} outputPath  Absolute path for the output client-env.json.
+ * @returns {{ plugin: function(): object, write: function(): Promise<string[]> }}
+ */
+function createClientEnvCollector(outputPath) {
+  const found = new Set();
+
+  /**
+   * Returns a Vite-compatible Rollup plugin instance that populates the
+   * shared Set.
+   *
+   * Call once per build pass.  Each call returns a distinct plugin object but
+   * all write to the same underlying Set.  The transform hook is purely
+   * observational — it returns null so Rollup leaves the source unchanged.
+   *
+   * @returns {object}
+   */
+  function plugin() {
+    return {
+      name: 'clay-client-env',
+
+      /**
+       * Scan each module for process.env.VAR_NAME references and add the
+       * variable name to the shared collector Set.
+       *
+       * Returning null signals to Rollup that no source transformation was
+       * performed, preserving the original code exactly.
+       *
+       * @param {string} code
+       * @returns {null}
+       */
+      transform(code) {
+        for (const match of code.matchAll(ENV_VAR_RE)) {
+          found.add(match[1]);
+        }
+        return null;
+      }
+    };
+  }
+
+  /**
+   * Write the accumulated env var names to client-env.json as a sorted array.
+   *
+   * Called once after all build passes complete so that a single atomic write
+   * covers process.env references from both view-mode and kiln-mode modules.
+   * Also called after each incremental rebuild in watch mode.
+   *
+   * amphora-html's addEnvVars() reads this file at server startup to determine
+   * which process.env values to forward to the browser as window.process.env.
+   *
+   * @returns {Promise<string[]>} sorted list of var names written
+   */
+  async function write() {
+    const vars = [...found].sort();
+
+    await fs.outputJson(outputPath, vars, { spaces: 2 });
+    return vars;
+  }
+
+  return { plugin, write };
+}
+
+module.exports = { createClientEnvCollector };