Add observability: health checks, request IDs, and structured logging

docs/SELF-HOSTING.md

@@ -89,6 +89,7 @@ cp .env.example .env.local
 | `NEXT_PUBLIC_SUPABASE_ANON_KEY` | accounts | The anon/publishable key. Safe in the browser — row-level security is what protects the data. |
 | `CRON_SECRET` | the retention sweep | At least 16 characters. Unset means the sweep endpoint refuses everything, including your scheduler. |
 | `NEXT_PUBLIC_SENTRY_DSN` | error reporting | Optional. Unset means no Sentry, browser or server. |
+| `LOG_LEVEL` | server logs | Optional. `fatal`, `error`, `warn`, `info`, `debug`, `trace` or `silent`. Unset means `info` in production and `debug` elsewhere. |
 
 Two things that will catch you out:
 
@@ -175,6 +176,25 @@ Then, in the browser:
 If step 2 says accounts are not set up, go back to section 3 — it is almost
 always `NEXT_PUBLIC_SUPABASE_URL` or `NEXT_PUBLIC_SUPABASE_ANON_KEY` missing.
 
+### Health, versions and logs
+
+`GET /api/health` answers 200 when everything the instance is configured to
+use responds, and 503 when the database does not. Point an uptime monitor at
+it. It also names the build:
+
+```sh
+curl -s https://your-host/api/health
+# {"status":"ok","version":"0.1.0","commit":"ce429f1","builtAt":"…","environment":"production",
+#  "checks":{"database":"ok","accounts":"configured","errorReporting":"configured"}}
+```
+
+Every response carries `X-App-Version`, `X-Commit-SHA` and `X-Request-ID`. In
+a browser console, `window.appVersion` says the same. The server logs one JSON
+object per line, and every line written while handling a request carries
+that request's `requestId`. To find what the server did for a request, search
+the logs for the `X-Request-ID` it returned. A caller's own `X-Request-ID` or
+`X-Correlation-ID` is kept when it is a plain token of up to 128 characters.
+
 ## 7. Deploy it somewhere
 
 The hosted instance runs on Vercel with **Root Directory** set to `suite`, and

suite/.env.example

@@ -40,3 +40,7 @@ NEXT_PUBLIC_SUPABASE_ANON_KEY=
 # unset means the sweep endpoint refuses everything, including Vercel. An
 # endpoint whose job is deleting fails closed.
 # CRON_SECRET=
+
+# Server log verbosity: fatal, error, warn, info, debug, trace or silent.
+# Unset means info in production and debug everywhere else.
+# LOG_LEVEL=

suite/app/api/accounts/delete/route.test.ts

@@ -20,6 +20,7 @@ vi.mock("@/lib/accounts/serverClient", () => ({
 vi.mock("@/lib/accounts/supabaseStore", () => ({ accountsStore: () => store }));
 
 const { POST } = await import("./route");
+const request = () => new Request("http://localhost/api/accounts/delete", { method: "POST" });
 
 beforeEach(() => {
   currentUserResult = { id: `user-${Math.random()}`, email: "a@example.com" };
@@ -30,9 +31,9 @@ test("account deletion past the limit is throttled, per account", async () => {
   // then stops at the missing service-role key (mocked env has neither), so
   // calls 1-5 land on that same 500, distinctly from the 429 call 6 must get.
   for (let i = 0; i < 5; i += 1) {
-    const response = await POST();
+    const response = await POST(request());
     expect(response.status).toBe(500);
   }
-  const sixth = await POST();
+  const sixth = await POST(request());
   expect(sixth.status).toBe(429);
 });

suite/app/api/accounts/delete/route.ts

@@ -5,16 +5,17 @@ import { deleteAccountHandler } from "@/lib/accounts/handlers";
 import { accountsStore } from "@/lib/accounts/supabaseStore";
 import { currentUser, serverClient } from "@/lib/accounts/serverClient";
 import { allow, CREATE_LIMIT } from "@/lib/server/rateLimit";
+import { requestLog } from "@/lib/server/log";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
-export async function POST() {
+export async function POST(request: Request) {
   try {
     return await deleteAccount();
   } catch (error) {
     // See the note in `../wedding/route.ts`.
-    console.error("[accounts] POST /api/accounts/delete", error);
+    requestLog(request).error({ err: error }, "[accounts] POST /api/accounts/delete");
     return NextResponse.json({ error: "Something went wrong. Please try again." }, { status: 500 });
   }
 }