Merge pull request #2167 from codeforboston/main

Deploy to PROD 6/16/26

Author: Mephistic

.gitignore

@@ -87,3 +87,8 @@ cert.txt
 
 # lets each user define their own vscode settings
 .vscode/settings.json
+
+.serena/
+# local MCP server config (contains auth tokens)
+.mcp.json
+mcp-server/create-agent-key.ts

.nvmrc

@@ -0,0 +1 @@
+20

.prettierignore

@@ -15,3 +15,5 @@ coverage
 storybook-static
 llm
 playwright-report
+CLAUDE.md
+.cursor/

.storybook/firebase-guards/auth.guard.js

@@ -0,0 +1,118 @@
+const authModule = require("@firebase/auth")
+const {
+  getStorybookAuthState,
+  setStorybookAuthState,
+  shouldAllowFirebaseCall,
+  throwBlockedFirebaseCall
+} = require("./common")
+
+function emitAuthState(callback) {
+  const { user } = getStorybookAuthState()
+  callback(user)
+}
+
+function block(apiName) {
+  return () => {
+    throwBlockedFirebaseCall(
+      "auth",
+      apiName,
+      "Mock auth state in your story providers or pass explicit props that avoid auth hooks."
+    )
+  }
+}
+
+function onAuthStateChanged(auth, nextOrObserver, error, completed) {
+  if (shouldAllowFirebaseCall()) {
+    return authModule.onAuthStateChanged(auth, nextOrObserver, error, completed)
+  }
+
+  const callback =
+    typeof nextOrObserver === "function"
+      ? nextOrObserver
+      : nextOrObserver?.next ?? (() => undefined)
+
+  emitAuthState(callback)
+
+  return () => undefined
+}
+
+function patchAuthInstance(auth) {
+  if (!auth || shouldAllowFirebaseCall()) return auth
+
+  return new Proxy(auth, {
+    get(target, prop, receiver) {
+      if (prop === "onAuthStateChanged") {
+        return onAuthStateChanged
+      }
+      return Reflect.get(target, prop, receiver)
+    }
+  })
+}
+
+function getAuth(...args) {
+  const auth = authModule.getAuth(...args)
+  return patchAuthInstance(auth)
+}
+
+function initializeAuth(...args) {
+  const auth = authModule.initializeAuth(...args)
+  return patchAuthInstance(auth)
+}
+
+module.exports = {
+  ...authModule,
+  getAuth,
+  initializeAuth,
+  onAuthStateChanged,
+  signInWithEmailAndPassword: block("signInWithEmailAndPassword"),
+  signInWithPopup: block("signInWithPopup"),
+  signInWithRedirect: block("signInWithRedirect"),
+  signInAnonymously: block("signInAnonymously"),
+  mockLoggedOutAuthState() {
+    return setStorybookAuthState({ user: null })
+  },
+  mockLoggedInUserAuthState(overrides = {}) {
+    const user = {
+      uid: "storybook-user",
+      email: "storybook-user@example.com",
+      emailVerified: true,
+      displayName: "Storybook User",
+      isAnonymous: false,
+      providerId: "firebase",
+      photoURL: null,
+      phoneNumber: null,
+      tenantId: null,
+      metadata: {
+        creationTime: "",
+        lastSignInTime: ""
+      },
+      providerData: [],
+      refreshToken: "storybook-refresh-token",
+      stsTokenManager: {
+        accessToken: "storybook-access-token",
+        refreshToken: "storybook-refresh-token",
+        expirationTime: Date.now() + 60 * 60 * 1000
+      },
+      getIdToken: async () => "storybook-id-token",
+      getIdTokenResult: async () => ({
+        token: "storybook-id-token",
+        authTime: "",
+        issuedAtTime: "",
+        expirationTime: "",
+        signInProvider: null,
+        claims: {
+          role: "user",
+          email_verified: true
+        }
+      }),
+      reload: async () => undefined,
+      delete: async () => undefined,
+      toJSON: () => ({})
+    }
+
+    return setStorybookAuthState({
+      user: { ...user, ...overrides },
+      claims: { role: "user", email_verified: true }
+    })
+  }
+}

.storybook/firebase-guards/common.js

@@ -0,0 +1,68 @@
+const ALLOW_FLAG = "__MAPLE_STORYBOOK_ALLOW_FIREBASE__"
+const WARNED_FLAG = "__MAPLE_STORYBOOK_FIREBASE_WARNED__"
+const AUTH_STATE_KEY = "__MAPLE_STORYBOOK_FIREBASE_AUTH_STATE__"
+
+function canAllowInRuntime() {
+  if (typeof globalThis !== "undefined") {
+    return Boolean(globalThis[ALLOW_FLAG])
+  }
+  return false
+}
+
+function canAllowFromEnv() {
+  return process.env.STORYBOOK_ALLOW_FIREBASE_CALLS === "1"
+}
+
+function shouldAllowFirebaseCall() {
+  return canAllowFromEnv() || canAllowInRuntime()
+}
+
+function warnOnce(key, message) {
+  if (typeof globalThis === "undefined") return
+
+  if (!globalThis[WARNED_FLAG]) {
+    globalThis[WARNED_FLAG] = new Set()
+  }
+
+  const warned = globalThis[WARNED_FLAG]
+  if (!warned.has(key)) {
+    warned.add(key)
+    console.warn(message)
+  }
+}
+
+function throwBlockedFirebaseCall(service, apiName, helpText) {
+  if (shouldAllowFirebaseCall()) return
+
+  const message = [
+    `[Storybook Firebase Guard] Blocked ${service} call: ${apiName}`,
+    "Real Firebase calls are disabled by default in Storybook.",
+    "Mock the component data/hooks used by this story instead.",
+    helpText,
+    "To opt out temporarily for a specific story, set: parameters.firebaseGuard.allow = true",
+    "To opt out globally, start Storybook with STORYBOOK_ALLOW_FIREBASE_CALLS=1"
+  ].join("\n")
+
+  warnOnce(`${service}:${apiName}`, message)
+  throw new Error(message)
+}
+
+function getStorybookAuthState() {
+  if (typeof globalThis === "undefined") return { user: null }
+
+  return globalThis[AUTH_STATE_KEY] ?? { user: null }
+}
+
+function setStorybookAuthState(state) {
+  if (typeof globalThis !== "undefined") {
+    globalThis[AUTH_STATE_KEY] = state
+  }
+  return state
+}
+
+module.exports = {
+  getStorybookAuthState,
+  setStorybookAuthState,
+  shouldAllowFirebaseCall,
+  throwBlockedFirebaseCall
+}

.storybook/firebase-guards/firestore.guard.js

@@ -0,0 +1,25 @@
+const firestore = require("@firebase/firestore")
+const { throwBlockedFirebaseCall } = require("./common")
+
+function block(apiName) {
+  return () => {
+    throwBlockedFirebaseCall(
+      "firestore",
+      apiName,
+      "Provide mocked query results or inject mock props into the component under test."
+    )
+  }
+}
+
+module.exports = {
+  ...firestore,
+  getDoc: block("getDoc"),
+  getDocs: block("getDocs"),
+  onSnapshot: block("onSnapshot"),
+  addDoc: block("addDoc"),
+  setDoc: block("setDoc"),
+  updateDoc: block("updateDoc"),
+  deleteDoc: block("deleteDoc"),
+  runTransaction: block("runTransaction"),
+  getCountFromServer: block("getCountFromServer")
+}

.storybook/main.js

@@ -1,6 +1,8 @@
 /**
  * @type {import('@storybook/react/types').StorybookConfig}
  */
+const path = require("path")
+
 module.exports = {
   stories: [
     "../stories/**/*.stories.mdx",
@@ -24,6 +26,28 @@ module.exports = {
       use: ["file-loader"]
     })
     config.resolve.fallback = { fs: false, path: false }
+
+    const path = require("path")
+    const webpack = require("webpack")
+    config.plugins.push(
+      new webpack.NormalModuleReplacementPlugin(
+        /components\/db\/profile\/profile(\.tsx?)?$/,
+        path.resolve(__dirname, "../stories/__mocks__/db/profile.ts")
+      )
+    )
+
+    config.resolve.alias = {
+      ...(config.resolve.alias || {}),
+      "firebase/firestore$": path.resolve(
+        __dirname,
+        "./firebase-guards/firestore.guard.js"
+      ),
+      "firebase/auth$": path.resolve(
+        __dirname,
+        "./firebase-guards/auth.guard.js"
+      )
+    }
+
     return config
   },
 

.storybook/preview.js

@@ -9,6 +9,9 @@ import React, { Suspense } from "react"
 import { I18nextProvider } from "react-i18next"
 // import i18n from "i18next"
 import i18n from "./i18n"
+const { mockLoggedOutAuthState } = require("./firebase-guards/auth.guard.js")
+
+mockLoggedOutAuthState()
 
 export const parameters = {
   actions: { argTypesRegex: "^on[A-Z].*" },
@@ -60,6 +63,12 @@ export const parameters = {
 
 export const decorators = [
   (Story, context) => {
+    if (typeof window !== "undefined") {
+      window.__MAPLE_STORYBOOK_ALLOW_FIREBASE__ = Boolean(
+        context?.parameters?.firebaseGuard?.allow
+      )
+    }
+
     return (
       <Suspense fallback="Loading...">
         <I18nextProvider i18n={i18n}>

README.md

@@ -68,6 +68,23 @@ git pull upstream main
 - `yarn dev:down`: Stop the application.
 - `yarn dev:update`: Update the application images. Run this whenever dependencies in `package.json` change.
 
+### Storybook Firebase Guard
+
+Storybook blocks real Firebase Auth and Firestore calls by default to prevent accidental network access from stories.
+
+If a story triggers a blocked call, Storybook throws an error with guidance about what to mock.
+
+Use these patterns when building stories:
+
+- Prefer passing mock props/data to components instead of rendering hook-driven containers.
+- If a component supports injection (for example, mock `profile`/`index` props), use that in the story args.
+- For auth-driven stories, use the helpers in [stories/utils/storybookFirebaseAuth.ts](stories/utils/storybookFirebaseAuth.ts) to switch between logged-out and logged-in user mocks.
+
+Opt-out options:
+
+- Per story: set `parameters.firebaseGuard.allow = true`.
+- Globally: run Storybook with `STORYBOOK_ALLOW_FIREBASE_CALLS=1`.
+
 Install the [Redux DevTools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd) and [React DevTools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi) browser extensions if you're developing frontend
 
 ## Contributing Backend Features to Dev/Prod: