Add resilience layer with caching and graceful degradation for Supabase outages

[ThorstenSuckow]

Summary

Implement a resilience layer that allows the website to remain functional when Supabase is temporarily unavailable. This includes caching signatories at build time and showing cached data with appropriate user feedback when the live connection fails.

Requirements

1. Signatory Caching System

• Build-time caching: Create a script (scripts/cache-signatories.cjs) that fetches signatories from Supabase and caches them to a local JSON file (src/data/cachedSignatories.json)
• Automatic execution: Run the cache script during prestart and prebuild npm lifecycle hooks
• Cache metadata: Include timestamp (cached_at) in the cached data for display purposes
• Gitignore: Add the cached signatories file to .gitignore (it's generated at build time)

2. Graceful Degradation

When Supabase is unavailable:

• SignersList component: Fall back to cached signatories with an error banner showing:
  • "Connection to Supabase failed. Showing cached signatories"
  • Display cache timestamp (e.g., "as of 12/5/2025, 10:30:00 AM")
• SignManifest component: Show warning banner indicating signing is temporarily disabled
• Disable sign buttons: All OAuth and name-only sign buttons should be disabled when Supabase is unavailable

3. Testing Support

• Environment variable: Add SIMULATE_SUPABASE_DOWN to .env for testing the fallback behavior
• Custom field: Expose this setting via docusaurus.config.ts customFields
• Console logging: Log a warning when simulation mode is active

4. UI Feedback

Add CSS styles for:

• Warning banners (yellow/amber theme) for the signing component
• Error banners for the signers list
• Cache date styling

5. Component Changes

SignManifest.tsx

• Track supabaseUnavailable state
• Show warning banner when unavailable
• Disable all sign buttons when unavailable
• Handle connection errors in session fetching

SignersList.tsx

• Add showErrorBanner prop (default: false)
• Fall back to cached data on fetch failure
• Track usingCache and error states
• Show error banner with cache date on signatories page

6. Configuration Updates

• package.json: Add cache:signatories script and include in pre-hooks
• docusaurus.config.ts: Add simulateSupabaseDown custom field
• .gitignore: Exclude cachedSignatories.json
• .env: Add SIMULATE_SUPABASE_DOWN=false

Files Changed

 .env                                     +1 (new env variable)
 .github/agents/ai-manifesto.agents.md   +2 (project guidelines)
 .gitignore                               +1 (exclude cache file)
 docusaurus.config.ts                     +1 (customField)
 package.json                             +5 (new script, hooks)
 src/components/SignManifest.module.css  +11 (warning banner styles)
 src/components/SignManifest.tsx         +53 (resilience logic)
 src/components/SignersList.module.css   +17 (error banner styles)
 src/components/SignersList.tsx          +81 (caching fallback)
 src/pages/signatories.tsx                +2 (showErrorBanner prop)
 scripts/cache-signatories.cjs           NEW (cache script)

Acceptance Criteria

• Website remains functional when Supabase is down
• Cached signatories are displayed with appropriate messaging
• Sign buttons are disabled with explanatory message
• Cache is refreshed on every build/start
• Simulation mode works for testing
• No console errors when Supabase is unavailable

Testing

1. Set SIMULATE_SUPABASE_DOWN=true in .env
2. Run npm start
3. Verify:
   • Warning banner appears in sign section
   • Sign buttons are disabled
   • Cached signatories are shown with cache date
   • Error banner appears on /signatories page