feat(showcase): add oxlint guard against NEXT_PUBLIC_* shell reads

Plan-B / Option-B migration moved every shell URL/analytics key off the
build-time NEXT_PUBLIC_* env channel and onto runtime config served via
__SHOWCASE_CONFIG__ + getRuntimeConfig(). To prevent a silent regression
where a future change reintroduces a direct process.env.NEXT_PUBLIC_*
read in shell code (which would re-freeze the value at build time and
break no-rebuild env switching), add a focused lint rule.

The rule (copilotkit/no-public-env-shell-read) is implemented as a
custom oxlint JS plugin rule in the existing copilotkit plugin and
enabled under shell-scoped overrides in .oxlintrc.json:

- Errors on process.env.NEXT_PUBLIC_<URL/ANALYTICS> reads in:
  showcase/shell-dashboard/src/**, showcase/shell-docs/src/**,
  showcase/shell/src/**, showcase/shell-dojo/src/**
- Banned keys: POCKETBASE_URL, SHELL_URL, BASE_URL, OPS_BASE_URL,
  INTELLIGENCE_SIGNUP_URL, POSTHOG_KEY, POSTHOG_HOST, SCARF_PIXEL_ID,
  GOOGLE_ANALYTICS_TRACKING_ID, REB2B_KEY, REO_KEY
- Intentionally allowed (NOT banned): NEXT_PUBLIC_COMMIT_SHA and
  NEXT_PUBLIC_BRANCH (build-stamped artifact identifiers per B10/B11)
  and NEXT_PUBLIC_LOCAL_BACKENDS (computed from shared/local-ports.json
  at build, local-dev only).
- Excluded files (rule disabled via a follow-up override): MDX content
  under shell-docs/src/content/**, runtime-config implementation files,
  and *.test.{ts,tsx} / *.spec.{ts,tsx}. oxlint does not support
  excludedFiles inside an override block, so the exclusion is expressed
  as a later override that sets the rule to off.

Plan-B originally targeted oxlint's eslint/no-restricted-syntax with an
AST-selector regex. oxlint 1.x does not implement that rule (only
no-restricted-globals / no-restricted-imports), so the equivalent guard
is realized as a small custom rule in the existing copilotkit JS plugin
(meta.name=copilotkit), reusing the same plugin loader the repo already
has for require-cpk-prefix and no-single-arg-zod-record.

Verification (red-green): the rule fires on a fixture containing
process.env.NEXT_PUBLIC_POCKETBASE_URL and does NOT fire on a fixture
containing process.env.NEXT_PUBLIC_COMMIT_SHA. Test pins the config via
-c so it works inside git worktrees nested under .claude/worktrees/
where oxlint's automatic upward config search can miss the worktree's
own .oxlintrc.json.

All four shells lint clean: 0 errors of the new rule across
shell-dashboard (114 files), shell-docs (137), shell (29), shell-dojo (6).

Author: jpr5

.oxlintrc.json

@@ -73,6 +73,28 @@
         "typescript/no-import-type-side-effects": "off",
         "import/consistent-type-specifier-style": "off"
       }
+    },
+    {
+      "files": [
+        "showcase/shell-dashboard/src/**/*.{ts,tsx}",
+        "showcase/shell-docs/src/**/*.{ts,tsx}",
+        "showcase/shell/src/**/*.{ts,tsx}",
+        "showcase/shell-dojo/src/**/*.{ts,tsx}"
+      ],
+      "rules": {
+        "copilotkit/no-public-env-shell-read": "error"
+      }
+    },
+    {
+      "files": [
+        "showcase/shell-docs/src/content/**",
+        "showcase/**/*runtime-config*",
+        "showcase/**/*.test.{ts,tsx}",
+        "showcase/**/*.spec.{ts,tsx}"
+      ],
+      "rules": {
+        "copilotkit/no-public-env-shell-read": "off"
+      }
     }
   ],
   "ignorePatterns": [

packages/react-ui/oxlint-rules/copilotkit-plugin.mjs

@@ -1,11 +1,13 @@
 import requireCpkPrefix from "./require-cpk-prefix.mjs";
 import noSingleArgZodRecord from "./no-single-arg-zod-record.mjs";
+import noPublicEnvShellRead from "./no-public-env-shell-read.mjs";
 
 const plugin = {
   meta: { name: "copilotkit" },
   rules: {
     "require-cpk-prefix": requireCpkPrefix,
     "no-single-arg-zod-record": noSingleArgZodRecord,
+    "no-public-env-shell-read": noPublicEnvShellRead,
   },
 };
 

packages/react-ui/oxlint-rules/no-public-env-shell-read.mjs

@@ -0,0 +1,106 @@
+/**
+ * Oxlint rule: no-public-env-shell-read
+ *
+ * Bans direct reads of `process.env.NEXT_PUBLIC_<URL/ANALYTICS>` keys in
+ * showcase shell client/server code. Those values are now served at runtime
+ * via `getRuntimeConfig()` (see workstream B / Option-B migration), and a
+ * stray `process.env.NEXT_PUBLIC_*` read would silently re-freeze the value
+ * at build time and regress the migration.
+ *
+ * Allowed (intentionally NOT in the banned set):
+ *   - `NEXT_PUBLIC_COMMIT_SHA`   — build-stamped artifact identifier
+ *   - `NEXT_PUBLIC_BRANCH`       — build-stamped artifact identifier
+ *   - `NEXT_PUBLIC_LOCAL_BACKENDS` — local-dev only, computed from
+ *     `shared/local-ports.json` at build time (not a real env var)
+ *
+ * Banned keys:
+ *   NEXT_PUBLIC_POCKETBASE_URL, NEXT_PUBLIC_SHELL_URL, NEXT_PUBLIC_BASE_URL,
+ *   NEXT_PUBLIC_OPS_BASE_URL, NEXT_PUBLIC_INTELLIGENCE_SIGNUP_URL,
+ *   NEXT_PUBLIC_POSTHOG_KEY, NEXT_PUBLIC_POSTHOG_HOST,
+ *   NEXT_PUBLIC_SCARF_PIXEL_ID, NEXT_PUBLIC_GOOGLE_ANALYTICS_TRACKING_ID,
+ *   NEXT_PUBLIC_REB2B_KEY, NEXT_PUBLIC_REO_KEY
+ *
+ * Scope is enforced via `overrides[].files` in `.oxlintrc.json` (shell
+ * source trees only; `.mdx` content, runtime-config implementation files,
+ * and tests are excluded by a follow-up override that turns this rule
+ * back off).
+ *
+ * Note: plan-B's original spec called for oxlint's `eslint/no-restricted-syntax`
+ * with an AST selector regex. oxlint 1.x does not implement that rule
+ * (only `no-restricted-globals` / `no-restricted-imports`), so we
+ * implement the equivalent guard as a focused custom rule in the existing
+ * copilotkit oxlint plugin instead.
+ */
+
+const BANNED_KEYS = new Set([
+  "NEXT_PUBLIC_POCKETBASE_URL",
+  "NEXT_PUBLIC_SHELL_URL",
+  "NEXT_PUBLIC_BASE_URL",
+  "NEXT_PUBLIC_OPS_BASE_URL",
+  "NEXT_PUBLIC_INTELLIGENCE_SIGNUP_URL",
+  "NEXT_PUBLIC_POSTHOG_KEY",
+  "NEXT_PUBLIC_POSTHOG_HOST",
+  "NEXT_PUBLIC_SCARF_PIXEL_ID",
+  "NEXT_PUBLIC_GOOGLE_ANALYTICS_TRACKING_ID",
+  "NEXT_PUBLIC_REB2B_KEY",
+  "NEXT_PUBLIC_REO_KEY",
+]);
+
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow direct `process.env.NEXT_PUBLIC_*` URL/analytics reads in shell code (use getRuntimeConfig)",
+    },
+    schema: [],
+    messages: {
+      forbiddenRead:
+        "Do not read process.env.NEXT_PUBLIC_* directly in shell code. Use getRuntimeConfig() from @/lib/runtime-config.client (client) or @/lib/runtime-config (server). See workstream B.",
+    },
+  },
+
+  create(context) {
+    return {
+      // Match `process.env.<KEY>` — i.e. a MemberExpression whose object is
+      // itself the MemberExpression `process.env` and whose property is the
+      // banned identifier.
+      MemberExpression(node) {
+        const obj = node.object;
+        if (
+          !obj ||
+          obj.type !== "MemberExpression" ||
+          obj.computed ||
+          !obj.object ||
+          obj.object.type !== "Identifier" ||
+          obj.object.name !== "process" ||
+          !obj.property ||
+          obj.property.type !== "Identifier" ||
+          obj.property.name !== "env"
+        ) {
+          return;
+        }
+        // `node.property` is the key being read off `process.env`.
+        // Only flag the static dotted form (`process.env.FOO`) or the
+        // literal-string computed form (`process.env["FOO"]`).
+        let keyName = null;
+        if (!node.computed && node.property && node.property.type === "Identifier") {
+          keyName = node.property.name;
+        } else if (
+          node.computed &&
+          node.property &&
+          node.property.type === "Literal" &&
+          typeof node.property.value === "string"
+        ) {
+          keyName = node.property.value;
+        }
+        if (!keyName) return;
+        if (!BANNED_KEYS.has(keyName)) return;
+
+        context.report({ node, messageId: "forbiddenRead" });
+      },
+    };
+  },
+};
+
+export default rule;

showcase/scripts/__tests__/lint-rule-no-public-env.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { execSync } from "node:child_process";
+import { writeFileSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+// Repo root is two directories above this test file
+// (showcase/scripts/__tests__/X -> showcase/scripts -> showcase -> <repo>).
+const REPO_ROOT = resolve(import.meta.dirname, "..", "..", "..");
+const CONFIG_PATH = join(REPO_ROOT, ".oxlintrc.json");
+
+describe("oxlint copilotkit/no-public-env-shell-read NEXT_PUBLIC_* guard", () => {
+    it("fires on direct process.env.NEXT_PUBLIC_POCKETBASE_URL read in shell code", () => {
+        // Stage a forbidden file inside the actual repo path so the
+        // override `files` pattern matches. We use a `.lintfixture.tsx`
+        // suffix that the off-override (which excludes `*.test.{ts,tsx}` /
+        // `*.spec.{ts,tsx}` / `*runtime-config*`) does NOT match.
+        const target = join(
+            REPO_ROOT,
+            "showcase",
+            "shell-dashboard",
+            "src",
+            "lib",
+            "__bad.lintfixture.tsx",
+        );
+        writeFileSync(
+            target,
+            `export const x = process.env.NEXT_PUBLIC_POCKETBASE_URL;\n`,
+            "utf8",
+        );
+        try {
+            // Use an explicit -c to pin the config: in git worktrees nested
+            // under .claude/worktrees/, oxlint's automatic upward config
+            // search may resolve to a different .oxlintrc.json than the
+            // worktree's own. Pinning it makes the test deterministic.
+            const result = execSync(
+                `npx oxlint -c ${CONFIG_PATH} ${target} --quiet`,
+                { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], cwd: REPO_ROOT },
+            ).toString();
+            // Should not reach here — oxlint exits non-zero on errors.
+            expect(result).toBe("UNREACHABLE: oxlint should have failed");
+        } catch (e) {
+            const stderr = (e as { stderr?: Buffer | string }).stderr?.toString() ?? "";
+            const stdout = (e as { stdout?: Buffer | string }).stdout?.toString() ?? "";
+            const combined = stderr + stdout;
+            expect(combined).toMatch(/no-public-env-shell-read/);
+            expect(combined).toMatch(/getRuntimeConfig/);
+        } finally {
+            rmSync(target, { force: true });
+        }
+    });
+
+    it("does NOT fire on process.env.NEXT_PUBLIC_COMMIT_SHA (build-stamp, intentionally allowed)", () => {
+        const target = join(
+            REPO_ROOT,
+            "showcase",
+            "shell-dashboard",
+            "src",
+            "lib",
+            "__ok.lintfixture.tsx",
+        );
+        writeFileSync(
+            target,
+            `export const sha = process.env.NEXT_PUBLIC_COMMIT_SHA;\n`,
+            "utf8",
+        );
+        try {
+            // Should succeed (exit 0).
+            execSync(`npx oxlint -c ${CONFIG_PATH} ${target} --quiet`, {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"],
+                cwd: REPO_ROOT,
+            });
+        } finally {
+            rmSync(target, { force: true });
+        }
+    });
+});