Merge branch 'main' into shayna-update-readme

Author: ShaynaCummings

.claude/settings.json

@@ -0,0 +1,6 @@
+{
+  "enabledPlugins": {
+    "csharp-lsp@claude-plugins-official": true,
+    "typescript-lsp@claude-plugins-official": true
+  }
+}

.github/workflows/playwright-e2e.yaml

@@ -0,0 +1,115 @@
+name: Playwright E2E
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  e2e:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    services:
+      mssql:
+        image: mcr.microsoft.com/mssql/server:2022-latest
+        env:
+          ACCEPT_EULA: Y
+          MSSQL_SA_PASSWORD: YourStrong@Passw0rd
+        ports:
+          - 1433:1433
+        options: >-
+          --health-cmd="/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P YourStrong@Passw0rd -Q 'SELECT 1' -C -b -o /dev/null || exit 1"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+          --health-start-period=10s
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Determine state connector ref
+        id: connector-ref
+        run: |
+          BRANCH="${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}"
+          FALLBACK="${{ github.event_name == 'pull_request' && github.base_ref || 'main' }}"
+          REPO_URL="https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository_owner }}/sebt-self-service-portal-state-connector.git"
+          if git ls-remote --exit-code --heads "$REPO_URL" "refs/heads/${BRANCH}" 1>/dev/null 2>&1; then
+            echo "ref=${BRANCH}" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=${FALLBACK}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout state connector
+        uses: actions/checkout@v4
+        with:
+          repository: codeforamerica/sebt-self-service-portal-state-connector
+          ref: ${{ steps.connector-ref.outputs.ref }}
+          path: state-connector
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: "10.0.200"
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: "10"
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --prefer-offline
+
+      - name: Build backend
+        run: ./.github/workflows/scripts/build-backend.sh --configuration Release
+
+      - name: Install Playwright browsers
+        run: cd src/SEBT.Portal.Web && pnpm exec playwright install --with-deps chromium
+
+      - name: Install Chrome for Pa11y
+        run: cd src/SEBT.Portal.Web && pnpm exec puppeteer browsers install chrome
+
+      - name: Run Pa11y and Playwright E2E tests
+        env:
+          CI: true
+          SKIP_WEB_SERVER: "1"
+          STATE: dc
+          NEXT_PUBLIC_STATE: dc
+          ASPNETCORE_ENVIRONMENT: Development
+          ConnectionStrings__DefaultConnection: "Server=localhost,1433;Database=SebtPortal;User Id=sa;Password=YourStrong@Passw0rd;TrustServerCertificate=True;"
+          JwtSettings__SecretKey: "ci-e2e-jwt-secret-at-least-32-characters-long"
+          IdentifierHasher__SecretKey: "ci-e2e-identifier-hasher-key-32chars"
+          Oidc__CompleteLoginSigningKey: "ci-e2e-oidc-signing-key-at-least-32-chars"
+          UseMockHouseholdData: "true"
+        run: |
+          pnpm dev &
+          echo "Waiting for server at http://localhost:3000..."
+          for i in $(seq 1 90); do
+            curl -sf --max-time 15 http://localhost:3000 > /dev/null && echo "Server ready" && break
+            sleep 2
+          done
+          curl -sf --max-time 15 http://localhost:3000 > /dev/null || (echo "Server failed to start" && exit 1)
+          echo "Running Pa11y accessibility tests..."
+          pnpm ci:test:a11y
+          echo "Running Playwright E2E tests..."
+          pnpm ci:test:e2e
+
+      - name: Upload Playwright report
+        uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with:
+          name: playwright-report
+          path: src/SEBT.Portal.Web/playwright-report/
+          retention-days: 7

.gitignore

@@ -438,6 +438,7 @@ FodyWeavers.xsd
 
 # AI
 CLAUDE.local.md
+.claude/settings.local.json
 
 # Developer-local workflow artifacts (branch context, PR reviews, screenshots)
 docs/.local/

.husky/pre-commit

@@ -21,7 +21,7 @@ cd "$PROJECT_ROOT"
 
 # Check if there are backend changes in staged files
 has_backend_changes() {
-  git diff --cached --name-only | grep -vE '^src/SEBT\.Portal\.Web' | grep -qE '^SEBT\.Portal\.sln$|^src/SEBT\.Portal\.|\.(csproj|sln)$' || return 1
+  git diff --cached --name-only | grep -vE '^src/SEBT\.Portal\.Web' | grep -qE '^SEBT\.Portal\.sln$|^src/SEBT\.Portal\.|\.(csproj|sln)$|^test/' || return 1
 }
 
 # Check if there are frontend changes in staged files
@@ -93,12 +93,20 @@ if [ "$BACKEND_CHANGES" = "true" ]; then
 
   if command -v dotnet &> /dev/null; then
     # Verify code formatting matches .editorconfig (fails if changes needed)
-    dotnet format SEBT.Portal.sln --verify-no-changes --verbosity quiet || {
+    # Exclude sibling repos (state-connector, dc-connector, co-connector) that get
+    # pulled in via conditional ProjectReference but live outside this repository.
+    dotnet format SEBT.Portal.sln --verify-no-changes --verbosity quiet \
+      --exclude ../sebt-self-service-portal-state-connector/ \
+      --exclude ../sebt-self-service-portal-dc-connector/ \
+      --exclude ../sebt-self-service-portal-co-connector/ || {
       log_error ".NET code formatting check failed - run 'dotnet format SEBT.Portal.sln' to fix"
       exit 1
     }
-    
-    dotnet format SEBT.Portal.sln analyzers --verify-no-changes --verbosity quiet || {
+
+    dotnet format SEBT.Portal.sln analyzers --verify-no-changes --verbosity quiet \
+      --exclude ../sebt-self-service-portal-state-connector/ \
+      --exclude ../sebt-self-service-portal-dc-connector/ \
+      --exclude ../sebt-self-service-portal-co-connector/ || {
       log_error ".NET analyzer checks failed - fix the reported issues"
       exit 1
     }
@@ -159,7 +167,10 @@ if [ "$BACKEND_CHANGES" = "true" ]; then
   cd "$PROJECT_ROOT"
 
   if command -v dotnet &> /dev/null; then
-    dotnet test --configuration Debug --verbosity quiet || {
+    # Exclude SqlServer tests (Testcontainers/SQL Server) from pre-commit.
+    # They run in CI but cause stack overflows locally when combined with
+    # the rest of the suite due to Docker resource pressure under parallelism.
+    dotnet test --configuration Debug --verbosity quiet --filter "Category!=SqlServer" || {
       log_error "Backend tests failed"
       exit 1
     }

.idea/.gitignore

@@ -0,0 +1,29 @@
+# 9. State Backend Health Checks Report Degraded, Not Unhealthy
+
+Date: 2026-03-17
+
+## Status
+
+Accepted
+
+## Context
+
+State connector plugins register health checks that verify connectivity to their backend systems (DC's SQL database, CO's CBMS API). Initially these checks reported `Unhealthy` when the backend was misconfigured or unreachable. In ASP.NET Core's health check framework, the overall `/health` endpoint status is the worst individual check status — so a single `Unhealthy` check makes the entire endpoint report `Unhealthy`, which can cause container orchestrators to kill and replace the container.
+
+The portal can still serve requests (login, static pages, cached data) when a state backend is down. Recycling the container won't fix a downstream outage and can cascade into a worse situation.
+
+## Decision
+
+State connector health checks always report `Degraded` — never `Unhealthy` — regardless of whether the issue is missing configuration or an unreachable backend. The structured JSON response from `/health` includes per-check descriptions and exception details, so monitoring and alerting can still distinguish between misconfiguration and connectivity failures.
+
+### Alternatives considered
+
+- **Report `Unhealthy` for connectivity failures, `Degraded` for missing config.** More semantically precise, but the operational consequence (container recycling) is undesirable in both cases.
+- **Have connectors report `Unhealthy` but remap to `Degraded` at the portal level.** ASP.NET Core's overall status is the worst individual status with no built-in remapping. A portal-side wrapper could intercept results, but adds complexity for the same operational outcome.
+- **Make the failure status configurable via appsettings.** Flexibility for future states, but adds a configuration knob that would likely be set once and forgotten — and increases maintenance burden for state partners. Can revisit if needed as more states onboard.
+
+## Consequences
+
+- The `/health` endpoint never returns `Unhealthy` due to a state backend issue, preventing aggressive container recycling.
+- Monitoring must inspect the per-check details (description, exception) in the JSON response rather than relying solely on the top-level status to detect backend outages.
+- The portal's own health (e.g., its database) can still report `Unhealthy` if needed in the future — this decision applies only to state connector checks.

.idea/.idea.SEBT.Portal/.idea/.gitignore

@@ -0,0 +1,63 @@
+# 9. Vendor-Agnostic Privacy-Aware Data Layer
+
+Date: 2026-03-16
+
+## Status
+
+Accepted
+
+## Context
+
+The portal needs analytics and observability to understand user behavior, measure feature adoption, and support operational monitoring. Multiple analytics vendors (e.g., Mixpanel, Google Analytics, Adobe Analytics) may be used across different state deployments, and vendor choices may change over time. Directly integrating vendor SDKs throughout the codebase would create tight coupling, make vendor switches expensive, and risk leaking PII to vendors that should not receive it.
+
+We need a single, canonical source of truth for page metadata, user attributes, and tracked events that:
+
+- Decouples application code from any specific analytics vendor.
+- Enforces privacy scoping so PII is only accessible to authorized consumers.
+- Supports multiple concurrent vendor integrations without code changes.
+- Is understandable and maintainable by state partner agencies after handoff.
+
+## Decision
+
+We adopt a **vendor-agnostic data layer** following the [W3C Customer Experience Digital Data Layer (CEDDL)](https://www.w3.org/2013/12/ceddl-201312.pdf) recommendations. The implementation lives in `src/SEBT.Portal.Web/src/lib/data-layer.ts` as a framework-agnostic TypeScript class.
+
+**Canonical data structure** bound to `window.digitalData`:
+
+- `page` — page-level metadata with `category` and `attribute` sub-objects.
+- `user` — user-level data with a `profile` sub-object.
+- `event[]` — append-only event log with `eventName`, `eventData`, `timeStamp`, and `scope`.
+- `privacy.accessCategories` — declared access scopes.
+- `initialized` — boolean flag indicating readiness.
+
+**Privacy-aware scoping:**
+
+- Each data element can be assigned one or more access scopes (e.g., `"default"`, `"analytics"`, `"marketing"`).
+- Page data is publicly readable by default (no scope restriction).
+- User data automatically receives `"default"` scope, restricting access unless explicitly broadened.
+- Scope inheritance walks the path hierarchy from specific to general, so child elements inherit parent scope restrictions.
+- Scope metadata is stored in a private `Map`, not on the data objects themselves.
+
+**Loose coupling via DOM CustomEvents:**
+
+- All mutations emit namespaced `CustomEvent`s on `document` (e.g., `digitalData:PageElementSet`, `digitalData:UserProfileSet`, `digitalData:EventTracked`).
+- Vendor integration bridges subscribe to these events and forward data according to their scope permissions.
+- A global `DataLayer:Initialized` event signals readiness.
+- An `eventTypes` object on the root provides type-safe event name constants for bridge consumers.
+
+**React integration** uses a `DataLayerProvider` component that initializes the data layer once on mount via `useRef`, wrapped as the outermost provider in the app layout.
+
+## Consequences
+
+- **Application code** calls `digitalData.page.set(...)`, `digitalData.user.set(...)`, and `digitalData.trackEvent(...)` without knowing which vendors consume the data.
+- **Adding a new vendor** requires only a new event listener bridge — no changes to application code or the data layer itself.
+- **Removing a vendor** means removing its bridge. No application code changes.
+- **PII protection** is enforced at the data layer boundary. A vendor bridge for `"analytics"` scope cannot read user data that only has `"default"` scope.
+- **State partners** can configure different vendor bridges per deployment without modifying the core portal.
+- **Testing** is straightforward because the class is framework-agnostic and testable with jsdom.
+
+## References
+
+- W3C CEDDL specification: https://www.w3.org/2013/12/ceddl-201312.pdf
+- Implementation: `src/SEBT.Portal.Web/src/lib/data-layer.ts`
+- Tests: `src/SEBT.Portal.Web/src/lib/data-layer.test.ts`
+- Provider: `src/SEBT.Portal.Web/src/providers/DataLayerProvider.tsx`