Restore and update AGENTS.md files for all packages

sschupbach-salesforce · sschupbach-salesforce · commit 7b1a4157e321 · 2026-06-21T15:41:22.000-05:00
Restores AI agent guidance removed in the previous cleanup commit, with
corrections and a new gov-components entry:

- Root AGENTS.md: fix LWC location (react-bridge, not react-uswds), correct
  component counts (59 react-uswds, 83 gov-components, 135 component-lab pages),
  fix e2e commands to match package.json scripts
- packages/react-uswds/AGENTS.md: remove stale claims that gateway/config live
  here (they are in react-bridge); add i18n pattern docs
- packages/react-bridge/AGENTS.md: remove stale sfGpsDsUsGovConfigLoader
  reference (not in this package); fix createLwcCallbackGateway naming
- packages/gov-components/AGENTS.md: new file — 83 gov-specific components,
  import rules, test commands
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,146 @@
+# AGENTS.md — GPS Design Systems React Monorepo
+
+This file tells AI coding agents how to work in this repository. Read it before making any changes.
+
+---
+
+## Repo structure
+
+```
+packages/
+  react-bridge/          ← Platform infrastructure (design-system-agnostic)
+    src/
+      gateway/           GatewayProvider, useGatewayQuery/Mutation, MockGateway,
+                         LwcCallbackGateway, GraphQLGateway, types
+      config/            AppConfigProvider, useConfig, useFeatureFlag
+      wizard/            createWizardStore (Zustand), useWizardStep (RHF + Zod)
+      pubsub/            usePlatformEvent (Platform Events / CDC)
+      utils/             stripProxy
+    main/default/lwc/    LWC host components: sfGpsDsReactMount, lwcReactConfigLoader,
+                         lwcConfigUtils, lwcEmpBridge
+
+  react-uswds/           ← USWDS design system package (@sfgps-ds/react-uswds)
+    src/
+      components/        59 React components (USWDS 3.x)
+      context/           SfGpsDsUsGovContext / Provider / useAssets
+      hooks/             useUniqueId, useAssets, useAccStyleTokens, useI18n
+      utils/             safeHtml, sanitizeHref, formUtils
+      i18n/              react-i18next integration
+      locales/           en.json and other locale bundles
+    main/default/
+      classes/           Apex controllers: AppConfigController, CaseController,
+                         ContactController, ApexFrontdoorService
+      networks/          Experience Cloud network metadata
+
+  gov-components/        ← Government-specific components (@gov-ido/gov-components)
+    src/
+      components/        83 gov-specific React components
+
+docs/                    All documentation — platform guides and design-system guides
+e2e/                     Playwright tests against local Vite fixture (no org required)
+showcase/                UIBundle showcase app for Salesforce React Experience Cloud
+apps/component-lab/      Local dev fixture — 135 component pages
+examples/                Reference app implementations for PS teams
+scripts/                 Utility scripts
+```
+
+**Package boundary rule:** `react-bridge` has zero imports from `react-uswds` or `gov-components`. It is platform infrastructure only. If code requires a design-system import, it belongs in that design-system package, not here.
+
+---
+
+## Commands
+
+### Install
+```bash
+npm ci                        # install from lockfile
+```
+
+### Build
+```bash
+npm run build                 # build all packages (tsup for react-uswds)
+npm run build --workspace=packages/react-uswds
+```
+
+### Test
+```bash
+npm run test --workspaces --if-present                       # all packages
+npm run test --workspace=packages/react-uswds                # USWDS unit tests
+npm run test --workspace=packages/react-bridge               # bridge unit tests
+npm run test --workspace=packages/gov-components             # gov-components unit tests
+npm run test:coverage --workspace=packages/react-uswds       # with coverage thresholds
+```
+
+### Lint & format
+```bash
+npm run lint                  # ESLint across all packages
+npm run format:check          # Prettier dry-run
+npm run format                # Prettier write
+```
+
+### E2E (local fixture — no org required)
+```bash
+npm run e2e                   # run against local Vite fixture
+npm run e2e:ui                # Playwright interactive UI
+npm run dev                   # start local Vite dev server (port 4173)
+```
+
+### Deploy to Salesforce
+```bash
+sf project deploy start --source-dir showcase/main/default/uiBundles --target-org BUILD
+sf org open --target-org BUILD
+```
+
+---
+
+## Key architectural constraints
+
+### React component rules
+- React components never import `@salesforce/` modules — those are resolved at LWC compile time and are unavailable in React context.
+- All form components are controlled inputs: the parent owns the value and passes it via props.
+- Use `useId()` for stable, SSR-safe unique IDs. It is deterministic, Concurrent-Mode-safe, and collision-free.
+
+### Security rules
+- Never call `DOMPurify(window)` at module evaluation time. Initialize lazily on first use.
+- Never use `document.activeElement` for focus management in components. Pass trigger elements explicitly.
+- Never use `relatedTarget.closest(...)` in blur handlers. Use a boolean ref flag instead.
+- Use `queueMicrotask`, not `setTimeout`, for post-render focus moves.
+
+### Import rules
+- Import `@salesforce/agentforce-conversation-client` only from `src/agentforce.ts`, never from `src/index.ts`
+- Never import `@salesforce/apex/*`, `@salesforce/label/*`, `@salesforce/schema/*`, `@salesforce/user/*`, `@salesforce/client/*`, `@salesforce/featureFlag/*`, `@salesforce/customPermission/*`, `@salesforce/resourceUrl/*`, or `@salesforce/messageChannel/*` in any React source file — these are LWC compile-time virtual modules and cannot be resolved by npm or any bundler. ESLint rule SB-1 enforces this as a build error.
+- Never import `@sfgps-ds/react-uswds` or `@gov-ido/gov-components` from any file in `packages/react-bridge/`. ESLint rule PB-1 enforces this.
+- Never use `JSON.parse(JSON.stringify(` in `packages/react-bridge/`. Use `stripProxy()` instead. ESLint rule SER-2 enforces this.
+
+---
+
+## What to do / what not to do
+
+### Do
+- Add new USWDS React components under `packages/react-uswds/src/components/<ComponentName>/`
+- Export new public components from `packages/react-uswds/src/index.ts`
+- Export Agentforce-specific components from `packages/react-uswds/src/agentforce.ts` (not the main barrel)
+- Add platform-agnostic infrastructure (gateways, stores, hooks) to `packages/react-bridge/src/`
+- Add gov-specific components under `packages/gov-components/src/components/<ComponentName>/`
+- Write Vitest tests alongside source in `src/**/__tests__/`
+- Write E2E tests in `e2e/tests/`
+
+### Do not
+- Import `@salesforce/agentforce-conversation-client` from the main barrel (`index.ts`) — it belongs in `agentforce.ts` only
+- Import `@salesforce/` LWC virtual modules (`@salesforce/apex/*`, `@salesforce/label/*`, etc.) in any React file — LWC compile-time modules; use the gateway abstraction instead (ESLint SB-1)
+- Import `@sfgps-ds/react-uswds` or `@gov-ido/gov-components` from `packages/react-bridge/` — bridge is design-system-agnostic (ESLint PB-1)
+- Use `JSON.parse(JSON.stringify(` for LWC→React data crossing — use `stripProxy()` instead (ESLint SER-2)
+- Call `DOMPurify(window)` at module evaluation time
+- Use `document.activeElement` for focus management in React components
+- Add `dompurify` back to `dependencies` in `react-uswds` — it is a `peerDependency` and externalized from the tsup bundle
+
+---
+
+## Known pre-existing issues
+- `safeHtml.test.ts` — all tests pass. If test `[SEC-1D]` regresses, the fix is the `afterSanitizeAttributes` hook in `getPurifier()` inside `src/utils/safeHtml.ts`.
+
+---
+
+## Testing philosophy
+- Unit tests live in `src/**/__tests__/` and must run in Node/jsdom without a Salesforce org.
+- E2E tests in `e2e/` run against a local Vite fixture. They do not require a Salesforce org.
+- Coverage thresholds are enforced at 80% for `react-uswds`. Do not lower them.
diff --git a/packages/gov-components/AGENTS.md b/packages/gov-components/AGENTS.md
@@ -0,0 +1,37 @@
+# AGENTS.md — packages/gov-components
+
+See the [root AGENTS.md](../../AGENTS.md) for full context. This file adds gov-components-specific rules.
+
+## What this package is
+
+Government-specific React components that complement the USWDS primitives in `react-uswds`. Published as `@gov-ido/gov-components`. Contains 83 components organized around government service patterns (case management, civic navigation, program enrollment, accessibility panels, etc.).
+
+Same structure as `react-uswds`:
+- `src/components/` — 83 government-specific components
+- `src/context/` — `GovI18nProvider`
+- `src/hooks/` — shared hooks
+- `src/i18n/` — react-i18next integration
+- `src/locales/` — locale bundles
+- `src/utils/` — shared utilities
+- `src/index.ts` — barrel export
+
+## Test commands
+
+```bash
+npm run test --workspace=packages/gov-components         # unit tests
+npm run test:coverage --workspace=packages/gov-components
+npm run build --workspace=packages/gov-components
+```
+
+## Adding a new component
+
+1. Create `src/components/<ComponentName>/<ComponentName>.tsx` and `index.ts`
+2. Export from `src/index.ts`
+3. Add tests to `src/components/<ComponentName>/__tests__/<ComponentName>.test.tsx` — include a vitest-axe accessibility assertion
+4. Add a SPEC.md in the component directory documenting the public prop contract
+
+## Import rules
+
+- May import from `@sfgps-ds/react-uswds` for USWDS primitives (Banner, Button, Alert, etc.)
+- Must NOT import from `packages/react-bridge/` — no gateway or config coupling in this package
+- Follow the same `safeHtml` / `sanitizeHref` security rules as `react-uswds`
diff --git a/packages/react-bridge/AGENTS.md b/packages/react-bridge/AGENTS.md
@@ -0,0 +1,81 @@
+# AGENTS.md — packages/react-bridge
+
+See the [root AGENTS.md](../../AGENTS.md) for full context. This file adds bridge-specific rules.
+
+## What this package is
+
+Platform infrastructure. Design-system-agnostic. Exports:
+
+**Gateway layer** — abstracts how React talks to the Salesforce backend:
+- `GatewayProvider` / `useGateway` — injects a Gateway instance into the component tree
+- `useGatewayQuery(key, resource, params?)` — TanStack Query wrapper for `gateway.get()`; re-fetches when `key` changes
+- `useGatewayMutation(resource, method?, idField?)` — TanStack Query wrapper for post/patch/delete; includes in-flight double-submit guard
+- `MockGateway` — in-memory implementation for tests and local dev; `.on('resource.method', handler)` fluent API
+- `createLwcCallbackGateway(dispatch)` — production impl that routes calls to Apex `@AuraEnabled` methods via the LWC host
+- `createGraphQLGateway(routes)` — production impl backed by `@salesforce/sdk-data` GraphQL API
+- `relayEdges(connection)` / `sfValue(field)` — helpers for unwrapping Salesforce GraphQL response shapes
+
+**Config layer** — typed org/user context from Apex Custom Metadata:
+- `AppConfigProvider` — Zod-validates the config object from the LWC host; safe defaults in production
+- `useConfig()` — returns `{ orgId, userId, userLocale, isProduction, featureFlags, agentforceAgentId }`
+- `useFeatureFlag(flag)` — returns `boolean`; defaults to `false` for absent or undefined flags
+
+**Wizard layer** — multi-step form state (Zustand + React Hook Form + Zod):
+- `createWizardStore<T>(initialPayload)` — factory that creates a typed Zustand store; call at module scope, never inside a component
+- `useWizardStep({ schema, storePayload, updatePayload, onNext })` — wires RHF + zodResolver to one step; reads `defaultValues` from store (preserves back-navigation); only calls `updatePayload` + `onNext` when Zod passes
+
+**Pub/Sub layer** — Platform Events and Change Data Capture:
+- `usePlatformEvent<T>({ envelope, channel, onEvent })` — reads the `__emp__` prop pushed by `lwcEmpBridge` via `_setReactProps`; deduplicates by `replayId`; ignores envelopes from other channels
+- `EmpEnvelope<T>` — type matching the `lightning/empApi` subscribe() message shape
+
+**LWC host components** (`main/default/lwc/`):
+- `sfGpsDsReactMount` — owns the `lwc:dom="manual"` div; mounts React via `ReactDOM.createRoot`
+- `lwcReactConfigLoader` — abstract base class; coordinates `loadScript`/`@wire(getConfig)` with React lifecycle; provides `_dispatch()` and `_setReactProps()` to subclasses
+- `lwcConfigUtils` — pure JS utilities: `stripProxy`, `normalizeApexError`, `createFrontdoorScheduler`
+- `lwcEmpBridge` — utility class (not a visual component); subscribes to `lightning/empApi` channels and forwards raw envelopes to React via `_setReactProps({ __emp__: envelope })`
+
+**Utils:**
+- `stripProxy(value)` — serialize `@salesforce/sdk-data` proxy membranes; required for any data crossing the LWC→React boundary
+
+## Hard rules
+
+**This package must have zero imports from `@sfgps-ds/react-uswds`, `@gov-ido/gov-components`, or any design-system package.**
+
+Choosing where to add new code:
+- Pure platform logic with no React/LWC imports → `lwcConfigUtils.js`
+- React hook or context that is design-system-agnostic → `packages/react-bridge/src/`
+- New abstract getter for design-system subclasses → abstract getter on `lwcReactConfigLoader` that throws when not implemented
+- USWDS-specific component or hook → `packages/react-uswds/`
+- Gov-specific component → `packages/gov-components/`
+
+## Test commands
+
+```bash
+npm run test --workspace=packages/react-bridge     # runs src/**/__tests__/**
+npm run test:watch --workspace=packages/react-bridge
+```
+
+Tests run in jsdom. `lightning/empApi` is aliased to `__mocks__/empApiMock.js`. `@salesforce/sdk-data` is aliased to `__mocks__/sdkDataMock.js`. LWC class code cannot be imported — use the harness pattern in `bridgeLifecycle.test.ts`.
+
+## Key invariants
+
+**`queryKey` must include all params that affect the response.** `useGatewayQuery(['contacts', accountId], 'contacts', { accountId })` — if `accountId` changes but the key stays `['contacts']`, TanStack will not refetch. The key controls cache identity; the params are forwarded to `gateway.get()` for the fetch itself.
+
+**`createWizardStore` at module scope, not inside a component.** A store created inside a component is recreated on every render, losing all accumulated payload. Create it once at the top level of the file that exports it.
+
+**`usePlatformEvent` channel must exactly match the empApi channel string.** `/event/CaseUpdate__e` and `/data/CaseChangeEvent` are different channels. The hook silently ignores envelopes whose `envelope.channel` does not match the `channel` option — this is intentional (a single `__emp__` prop carries all subscriptions).
+
+**`stripProxy` is the only safe serializer** for data crossing the LWC→React boundary. `JSON.parse(JSON.stringify())` silently destroys `Map`/`Set`, converts `BigInt` to a throw, and mangles `Date`. See `lwcConfigUtils.js` and `src/utils/stripProxy.ts`.
+
+## Adding a new abstract getter
+
+If you need `lwcReactConfigLoader` to accept a new design-system-specific value (e.g. a second stylesheet path), add an abstract getter that throws when not implemented:
+
+```js
+// lwcReactConfigLoader.js
+get _myNewGetter() {
+  throw new Error('lwcReactConfigLoader: _myNewGetter not implemented — override in subclass');
+}
+```
+
+Forgetting this step causes a runtime throw before React mounts.
diff --git a/packages/react-uswds/AGENTS.md b/packages/react-uswds/AGENTS.md
@@ -0,0 +1,54 @@
+# AGENTS.md — packages/react-uswds
+
+See the [root AGENTS.md](../../AGENTS.md) for full context. This file adds USWDS-package-specific rules.
+
+## What this package is
+
+The USWDS 3.x design system implementation. Contains:
+- React components (`src/components/`) — 59 USWDS UI primitives
+- Context, hooks, and i18n (`src/context/`, `src/hooks/`, `src/i18n/`, `src/locales/`)
+- Security utilities (`src/utils/`) — `safeHtml`, `sanitizeHref`, `formUtils`
+- Apex controllers (`main/default/classes/`) — `AppConfigController`, `CaseController`, `ContactController`, `ApexFrontdoorService`
+- Network metadata (`main/default/networks/`)
+
+**Gateway, config, wizard, and pubsub infrastructure live in `packages/react-bridge/`, not here.**
+
+## Test commands
+
+```bash
+npm run test --workspace=packages/react-uswds         # unit tests (src/**/__tests__/)
+npm run test:coverage --workspace=packages/react-uswds # must maintain 80% thresholds
+npm run build --workspace=packages/react-uswds        # tsup build -> dist/
+```
+
+## Adding a new component
+
+1. Create `src/components/<ComponentName>/<ComponentName>.tsx` and `index.ts`
+2. Export from `src/index.ts` (main barrel) — or `src/agentforce.ts` if Salesforce-product-specific
+3. Add tests to `src/components/<ComponentName>/__tests__/<ComponentName>.test.tsx`
+4. Add a SPEC.md in the component directory documenting the public contract
+5. Add an E2E fixture page in `e2e/fixtures/src/pages/<ComponentName>Page.tsx` and route it in `e2e/fixtures/src/main.tsx`
+6. Add an E2E spec in `e2e/tests/<componentname>.spec.ts`
+
+## Barrel export rules
+
+- **`src/index.ts`** — USWDS components, hooks, context, form utilities, sanitization. No `@salesforce/agentforce-conversation-client` imports.
+- **`src/agentforce.ts`** — `AgentforceWidget` only. Importing from this sub-path (`@sfgps-ds/react-uswds/agentforce`) requires `@salesforce/agentforce-conversation-client` as a peer.
+
+Never re-add `AgentforceWidget` to the main barrel. It pulls in the ACC SDK for every consumer regardless of whether they use Agentforce.
+
+## Security constraints
+
+- All rich HTML from LWC props must go through `safeHtml()` before rendering as raw markup.
+- All `<a href>` values must go through `sanitizeHref()`.
+- The `afterSanitizeAttributes` hook in `safeHtml.ts` removes `data:` URIs — do not remove or restructure `getPurifier()` without running the full `safeHtml.test.ts` suite, including the SEC-1D test.
+
+## dompurify is a peer dependency
+
+Do not add `dompurify` back to `dependencies`. It is a `peerDependency` and is externalized in `tsup.config.ts`. Consumers that use rich HTML components must install it themselves.
+
+## i18n pattern
+
+Replace hardcoded UI strings (aria-labels, validation messages, button text) with `t('namespace.key')` using the `useI18n()` hook. Add English strings to `src/locales/en.json`. Use the prop-override pattern: `propValue ?? t('key')` so callers can always pass their own string.
+
+Every component with i18n strings needs an `__tests__/<ComponentName>.i18n.test.tsx` that verifies translated strings render and prop overrides win.
