feat: add Sentry error capture helper, conventions, and regression test (#80) (#84)

- Add captureSupabaseError() in src/lib/sentry.ts for structured Sentry
  reporting of Supabase errors (PostgrestError and generic Error)
- Add Error Handling section to .agents/conventions.md documenting rules
  for mutations, catch blocks, and client-side error handling
- Add static analysis test scanning for bare catch {} and console.error
  without Sentry capture, with allowlist for known exceptions
- Delete dead sentry.client.config.ts (Turbopack never loads it;
  instrumentation-client.ts is the correct client init)
- Update architecture.md component map

Co-authored-by: Ona <no-reply@ona.com>

Author: zacharias-ona

.agents/architecture.md

@@ -220,6 +220,7 @@ src/
 │       ├── table.tsx
 │       └── tooltip.tsx
 ├── lib/
+│   ├── sentry.ts           # captureSupabaseError helper (structured Sentry reporting)
 │   ├── utils.ts            # cn() utility (clsx + tailwind-merge)
 │   ├── types.ts            # Database entity types
 │   ├── workspace.ts        # Workspace utilities: slug generation, validation, limits
@@ -234,7 +235,6 @@ Root config files:
 ├── instrumentation-client.ts  # Sentry client init (replay, route transitions)
 ├── sentry.server.config.ts    # Sentry server SDK config
 ├── sentry.edge.config.ts      # Sentry edge SDK config
-├── sentry.client.config.ts    # Sentry client SDK config
 └── components.json            # shadcn/ui config (base-nova style, Tailwind v4)
 ```
 

.agents/conventions.md

@@ -117,6 +117,71 @@ The `updateSession` function in `src/lib/supabase/proxy.ts` creates a server cli
 that reads cookies from the request and writes refreshed cookies to the response.
 It calls `supabase.auth.getUser()` to trigger the refresh.
 
+## Error Handling
+
+All errors must reach Sentry. `console.error` alone is never sufficient — always
+pair with a Sentry capture call. Bare `catch {}` is banned except for documented
+exceptions (see allowlist below).
+
+### Supabase mutations
+
+Every Supabase mutation must check the error return and call `captureSupabaseError`:
+
+```typescript
+import { captureSupabaseError } from "@/lib/sentry";
+
+const { error } = await supabase.from("pages").update({ title }).eq("id", pageId);
+if (error) {
+  captureSupabaseError(error, "pages.update");
+  // handle the error (toast, return error response, etc.)
+}
+```
+
+The helper accepts `PostgrestError` (from query results) and generic `Error` (from
+catch blocks). It tags the Sentry event with the operation name, error code, and
+message so errors are filterable in the Sentry dashboard.
+
+### API route catch blocks
+
+All catch blocks in API routes must call `Sentry.captureException`:
+
+```typescript
+import * as Sentry from "@sentry/nextjs";
+
+try {
+  // ... route logic
+} catch (error) {
+  Sentry.captureException(error);
+  return NextResponse.json({ error: "Internal server error" }, { status: 500 });
+}
+```
+
+### Client-side mutations
+
+Client-side mutations must show `toast.error()` on failure in addition to Sentry
+capture:
+
+```typescript
+import { captureSupabaseError } from "@/lib/sentry";
+import { toast } from "sonner";
+
+const { error } = await supabase.from("pages").insert({ ... });
+if (error) {
+  captureSupabaseError(error, "pages.insert");
+  toast.error("Failed to create page");
+}
+```
+
+### Bare catch allowlist
+
+These files have intentional bare `catch {}` blocks with documented reasons:
+
+- `src/lib/supabase/server.ts` — cookie `setAll` in Server Components (can't set cookies, safe to ignore)
+- `src/components/editor/editor.tsx` — URL validation (`new URL()` throws on invalid input)
+- `src/app/api/health/route.ts` — intentionally silent, monitored by Performance Monitor
+
+All other catch blocks must capture the error variable and report to Sentry.
+
 ## Environment Variable Guards
 
 Route handlers and server utilities that use Supabase must guard against missing

sentry.client.config.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from "vitest";
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join, relative } from "path";
+
+/**
+ * Static analysis tests for error handling conventions (Issue #80).
+ *
+ * Scans source files for bare `catch {}` blocks and `console.error` calls
+ * without accompanying Sentry capture. Files that will be fixed in subsequent
+ * PRs are allowlisted — those PRs must remove their file from the allowlist.
+ */
+
+const SRC_DIR = join(__dirname, "..");
+
+/** Files with intentional bare `catch {}` that are permanently allowed. */
+const BARE_CATCH_PERMANENT_ALLOWLIST = new Set([
+  "src/lib/supabase/server.ts", // cookie setAll in Server Components
+  "src/components/editor/editor.tsx", // URL validation (new URL() throws)
+  "src/app/api/health/route.ts", // intentionally silent, monitored externally
+]);
+
+/**
+ * Files with bare `catch {}` that will be fixed in subsequent PRs.
+ * Each entry should reference the issue that will fix it.
+ */
+const BARE_CATCH_PENDING_ALLOWLIST = new Set([
+  "src/components/sidebar/page-search.tsx", // #81 or follow-up
+  "src/app/api/search/route.ts", // #81 or follow-up
+]);
+
+const BARE_CATCH_ALLOWLIST = new Set([
+  ...BARE_CATCH_PERMANENT_ALLOWLIST,
+  ...BARE_CATCH_PENDING_ALLOWLIST,
+]);
+
+/**
+ * Files with `console.error` without Sentry capture that will be fixed
+ * in subsequent PRs.
+ */
+const CONSOLE_ERROR_PENDING_ALLOWLIST = new Set([
+  "src/components/editor/image-plugin.tsx", // #81 or follow-up
+  "src/components/page-menu.tsx", // #81 or follow-up
+]);
+
+function collectTsFiles(dir: string): string[] {
+  const files: string[] = [];
+
+  function walk(d: string) {
+    for (const entry of readdirSync(d)) {
+      const full = join(d, entry);
+      const stat = statSync(full);
+      if (stat.isDirectory()) {
+        walk(full);
+      } else if (/\.(ts|tsx)$/.test(entry) && !entry.endsWith(".test.ts") && !entry.endsWith(".test.tsx")) {
+        files.push(full);
+      }
+    }
+  }
+
+  walk(dir);
+  return files;
+}
+
+function toRelative(absPath: string): string {
+  return relative(join(SRC_DIR, ".."), absPath);
+}
+
+describe("error handling conventions", () => {
+  const files = collectTsFiles(SRC_DIR);
+
+  it("no bare catch {} outside the allowlist", () => {
+    const violations: string[] = [];
+
+    for (const file of files) {
+      const rel = toRelative(file);
+      if (BARE_CATCH_ALLOWLIST.has(rel)) continue;
+
+      const content = readFileSync(file, "utf-8");
+      // Match `catch {` or `catch  {` (bare catch without error variable)
+      // but not `catch (error)` or `catch (e)`
+      const bareCatchPattern = /\bcatch\s*\{/g;
+      let match;
+      while ((match = bareCatchPattern.exec(content)) !== null) {
+        const line = content.slice(0, match.index).split("\n").length;
+        violations.push(`${rel}:${line}`);
+      }
+    }
+
+    expect(
+      violations,
+      `Bare catch {} found outside allowlist. Either capture the error and report to Sentry, or add to the allowlist with a comment explaining why:\n${violations.join("\n")}`,
+    ).toEqual([]);
+  });
+
+  it("no console.error without Sentry capture outside the allowlist", () => {
+    const violations: string[] = [];
+
+    for (const file of files) {
+      const rel = toRelative(file);
+      if (CONSOLE_ERROR_PENDING_ALLOWLIST.has(rel)) continue;
+
+      const content = readFileSync(file, "utf-8");
+      const lines = content.split("\n");
+
+      for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes("console.error")) {
+          // Check if Sentry capture exists anywhere in the same file
+          const hasSentryCapture =
+            content.includes("Sentry.captureException") ||
+            content.includes("captureSupabaseError");
+
+          if (!hasSentryCapture) {
+            violations.push(`${rel}:${i + 1}`);
+          }
+        }
+      }
+    }
+
+    expect(
+      violations,
+      `console.error without Sentry capture found outside allowlist. Add Sentry.captureException or captureSupabaseError:\n${violations.join("\n")}`,
+    ).toEqual([]);
+  });
+});

src/lib/sentry.test.ts

@@ -0,0 +1,27 @@
+import * as Sentry from "@sentry/nextjs";
+import { PostgrestError } from "@supabase/supabase-js";
+
+/**
+ * Report a Supabase error to Sentry with structured context.
+ *
+ * Accepts both PostgrestError (from query/mutation results) and generic Error
+ * (from catch blocks). The `operation` tag makes it easy to filter in Sentry
+ * by the database operation that failed.
+ */
+export function captureSupabaseError(
+  error: PostgrestError | Error,
+  operation: string,
+): void {
+  const extra: Record<string, string> = {
+    operation,
+    message: error.message,
+  };
+
+  if (error instanceof PostgrestError) {
+    extra.code = error.code;
+    extra.details = error.details;
+    extra.hint = error.hint;
+  }
+
+  Sentry.captureException(error, { extra });
+}