Files
Andrew Beveridge ☄️andClaude Opus 4.7 6445864534 feat: frontend crash reporting → Discord alerts + auto cache bust (#725)
@coderabbitai ignore

## Summary

Gives us long-term peace of mind that frontend errors never reach users
silently. Every client-side crash is captured, shown to the user with
useful debug info, reported to the backend, alerted via the existing
Discord error channel, and — critically — after a fix ships, affected
users pick it up automatically.

## What this does

- **Backend endpoint** `POST /api/client-errors` — normalises inbound
reports and upserts into the same `error_patterns` Firestore collection
the backend already uses. No new Discord wiring needed:
`service="frontend"` patterns flow through the existing error-monitor
Cloud Run Job → Discord pipeline.
- **Three capture layers on the frontend**:
- Global `window.onerror` + `unhandledrejection` listeners (mounted once
per tab via `ClientErrorInit` in the locale layout)
- Next.js App Router `error.tsx` (per-locale) + `global-error.tsx`
(last-resort root)
- React `CrashReportBoundary` wrapping `LyricsReviewWrapper` +
`InstrumentalReviewWrapper` so a crash there renders in place rather
than white-screening the route
- **User-facing `CrashReport` card** — shows error name/message +
collapsible stack + debug info + build SHA; auto-sends on mount (catches
bugs in the wild without user action); has Copy / Send again / Try again
/ Back buttons.
- **Version-aware cache busting** so the next bug I fix actually reaches
affected users:
- `public/version.json` emitted at build time via a new `prebuild` hook.
- `isStale()` compares the compiled `NEXT_PUBLIC_COMMIT_SHA` against the
live `/version.json`.
- `ChunkLoadError` in the global handlers triggers a hard reload
(unregisters SWs, clears caches, navigates with `?_v=<sha>`
query-string) behind a 60 s circuit breaker to prevent reload loops.
- `CrashReport` shows a prominent "A newer version is available — Update
now" banner when stale; demotes "Try again" to secondary in that case.
- Ambient 10-minute poll dispatches a `karaoke:stale-version`
CustomEvent (no auto-reload ambient — only on crash).
- **Admin `/admin/_crash-test` page** — three buttons that fire async
throw / unhandled rejection / render-time throw, for post-deploy
pipeline verification.
- **Rate limiting** on the endpoint: 60/min per IP sliding window, plus
pattern-hash dedup collapsing viral bugs to a single pattern.
- **Privacy**: URL query strings + fragments stripped; user email only
sent if authenticated; no cookies / localStorage / form-value capture.
- **i18n**: `crashReport` namespace in `en.json` translated into all 32
locales.

Reuses existing env var `NEXT_PUBLIC_COMMIT_SHA` — no new build config.

## Review & verification

- 49 Jest suites / 800 tests pass (`make test`).
- New unit tests: `crash-reporter.test.ts`, `CrashReport.test.tsx`,
`CrashReportBoundary.test.tsx`, `version-check.test.ts`,
`test_frontend_ingestion.py`, `test_client_errors.py` — all green.
- Implemented task-by-task via subagent-driven workflow with spec + code
quality review per task (see
`docs/archive/2026-04-19-frontend-crash-reporting-plan.md`).
- E2E Playwright test deferred — the admin crash-test page covers manual
post-deploy verification.

## Test plan

- [ ] Deploy to prod.
- [ ] Visit `https://gen.nomadkaraoke.com/admin/_crash-test` as admin;
click each of the three buttons.
- [ ] Confirm a Discord alert arrives in the error channel (may take up
to ~15 min per the monitor Cloud Run schedule).
- [ ] Verify Firestore `error_patterns` contains 3 new docs with
`service="frontend"`.
- [ ] In a separate browser session already open to the app, simulate a
stale-bundle scenario (edit `public/version.json` on the CDN, or use an
older tab after a new deploy) — confirm `CrashReport` shows the "Update
now" banner if an error is thrown.
- [ ] Test the original Firefox Android bug (if it reproduces) and
verify the crash now lands in Discord with a usable stack trace.

## Follow-ups

- Source-map upload for readable production stacks (`Task 15` in the
plan).
- Consider forwarding the `source` payload field into
`PatternData.sample_message` if finer-grained Discord triage
(`window.onerror` vs `unhandledrejection` vs boundary) becomes valuable.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-19 21:14:12 -04:00

47 lines
1.4 KiB
JavaScript

#!/usr/bin/env node
/**
* Emit public/version.json with build SHA + timestamp.
*
* Runs as `prebuild` before `next build`. The JSON file is served as a static
* asset; the frontend fetches it at runtime to detect stale bundles.
*
* SHA sources (first match wins):
* 1. NEXT_PUBLIC_COMMIT_SHA (set by CI — matches the value baked into bundles)
* 2. CF_PAGES_COMMIT_SHA (Cloudflare Pages fallback)
* 3. GITHUB_SHA (GitHub Actions fallback)
* 4. git rev-parse HEAD (local dev)
* 5. "dev" (fallback)
*/
import { execSync } from 'node:child_process'
import { writeFileSync, mkdirSync } from 'node:fs'
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)
function gitSha() {
try {
return execSync('git rev-parse HEAD', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim()
} catch {
return null
}
}
const sha =
process.env.NEXT_PUBLIC_COMMIT_SHA ||
process.env.CF_PAGES_COMMIT_SHA ||
process.env.GITHUB_SHA ||
gitSha() ||
'dev'
const payload = {
build_sha: sha,
built_at: new Date().toISOString(),
}
const outPath = resolve(__dirname, '..', 'public', 'version.json')
mkdirSync(dirname(outPath), { recursive: true })
writeFileSync(outPath, JSON.stringify(payload, null, 2) + '\n', 'utf8')
console.log(`[write-version] wrote ${outPath}: ${JSON.stringify(payload)}`)