feat: real-time bot logs and health monitoring dashboard

.gitignore

@@ -1,7 +1,7 @@
 node_modules/
 .env
 *.log
-logs/
+/logs/
 coverage/
 .next/
 
@@ -13,7 +13,7 @@ coverage/
 .claude_settings.json
 .worktrees/
 .security-key
-logs/security/
+/logs/security/
 
 # State persistence data (keep structure, ignore content)
 data/*
@@ -38,3 +38,7 @@ web/.env.local
 web/.env.*.local
 web/tsconfig.tsbuildinfo
 
+# Un-ignore Next.js route that happens to be named "logs"
+!web/src/app/dashboard/logs/
+!web/src/app/dashboard/logs/**
+

TASK.md

@@ -0,0 +1,101 @@
+# Task: Health Cards + Restart History UI
+
+## Parent
+- **Master Task:** task-001
+- **Branch:** feat/logs-and-health
+- **Issue:** [#35](https://github.com/VolvoxLLC/volvox-bot/issues/35)
+
+## Context
+
+Build health metric cards and restart history table for the dashboard. Data comes from the extended health endpoint (`GET /api/v1/health`).
+
+### Existing Code
+- `web/src/lib/bot-api-proxy.ts` — API proxy for authenticated requests
+- `web/src/components/dashboard/config-editor.tsx` — Reference for dashboard patterns
+- `web/src/components/ui/` — shadcn/ui components (card, table, badge, etc.)
+- Health endpoint returns: uptime, memory, discord, system, errors, restarts
+
+## IMPORTANT — READ FIRST
+
+1. **Commit after every file you create or major change**
+2. **Start writing code IMMEDIATELY**
+3. **Expected duration: ~15m**
+
+**Commit flow:**
+1. Create health cards component → commit
+2. Create restart history component → commit
+3. Create page or section → commit
+4. Lint/build → commit
+
+## Files to Create
+
+- `web/src/components/dashboard/health-cards.tsx` — Health metric cards
+- `web/src/components/dashboard/restart-history.tsx` — Restart log table
+- `web/src/app/dashboard/logs/page.tsx` — Add health section (if page exists from log viewer slice, just add to it — otherwise create)
+
+## Requirements
+
+- [ ] **Health cards** (grid layout):
+  | Card | Data | Display |
+  |------|------|---------|
+  | Uptime | `health.uptime` | Human-readable ("3d 14h 22m") |
+  | Memory | `health.memory.heapUsed/heapTotal` | MB + percentage bar |
+  | Discord Ping | `health.discord.ping` | ms, color: green <100, yellow <300, red >300 |
+  | Guilds | `health.discord.guilds` | Count |
+  | Errors (1h) | `health.errors.lastHour` | Count, red if >0 |
+  | Errors (24h) | `health.errors.lastDay` | Count |
+  | CPU | `health.system.cpuUsage` | user + system % |
+  | Node | `health.system.nodeVersion` | Version string |
+- [ ] **Restart history table**:
+  - Columns: timestamp, reason, version, uptime before restart
+  - Last 20 restarts from `health.restarts`
+  - Human-readable timestamps
+  - Color-coded reasons (startup=green, crash=red)
+- [ ] Auto-refresh health data every 60s
+- [ ] Loading skeleton while fetching
+- [ ] Lint passes, build succeeds
+
+## Constraints
+- Do NOT touch backend files
+- Do NOT touch log viewer (different slice)
+- Use shadcn/ui Card, Table, Badge components
+- Use Tailwind for styling
+
+## Acceptance Criteria
+- [ ] Health cards display all 8 metrics
+- [ ] Color coding works for ping and errors
+- [ ] Restart history table shows recent restarts
+- [ ] Auto-refresh every 60s
+- [ ] Loading state while fetching
+- [ ] Lint + build pass
+
+## Results
+
+**Status:** ✅ Done
+
+**Commits:**
+- `45f908d` feat: add bot health API proxy route
+- `3c213c5` feat: add health cards component and shared types
+- `c71f821` feat: add restart history table component
+- `8157ffe` feat: add health section orchestrator and logs page; fix gitignore for logs route
+
+**Changes:**
+- `web/src/app/api/bot-health/route.ts` — authenticated proxy to bot's `GET /api/v1/health`
+- `web/src/components/dashboard/types.ts` — `BotHealth` / `RestartRecord` types + runtime validator
+- `web/src/components/dashboard/health-cards.tsx` — 8-card grid (uptime, memory + bar, discord ping w/ color, guilds, errors 1h/24h w/ red, CPU, Node version)
+- `web/src/components/dashboard/restart-history.tsx` — table with last 20 restarts, color-coded reason badges, human-readable timestamps
+- `web/src/components/dashboard/health-section.tsx` — client component with auto-refresh (60s), loading skeleton, error banner, refresh button
+- `web/src/app/dashboard/logs/page.tsx` — new `/dashboard/logs` route rendering `<HealthSection />`
+- `.gitignore` — added exception for `web/src/app/dashboard/logs/` (conflicts with `logs/` gitignore rule)
+
+**Build:** ✅ `next build` — compiled successfully, `/dashboard/logs` route created
+**TypeCheck:** ✅ `tsc --noEmit` — no errors in new files
+**Root lint:** Pre-existing failures in bot JS files only (26 errors existed before this task)
+
+**Acceptance Criteria:**
+- [x] Health cards display all 8 metrics
+- [x] Color coding works for ping (green/yellow/red) and errors (red if >0)
+- [x] Restart history table shows recent restarts (last 20, reversed)
+- [x] Auto-refresh every 60s
+- [x] Loading state while fetching (skeleton cards + table skeleton)
+- [x] Lint + build pass (build ✅, root lint pre-existing failures not introduced by this task)

package.json

@@ -27,7 +27,8 @@
     "pg": "^8.18.0",
     "winston": "^3.19.0",
     "winston-daily-rotate-file": "^5.0.0",
-    "winston-transport": "^4.9.0"
+    "winston-transport": "^4.9.0",
+    "ws": "^8.19.0"
   },
   "pnpm": {
     "overrides": {

src/api/routes/health.js

@@ -5,16 +5,26 @@
  */
 
 import { Router } from 'express';
+import { queryLogs } from '../../utils/logQuery.js';
 import { isValidSecret } from '../middleware/auth.js';
 
 const router = Router();
 
+// Graceful fallback for restartTracker — may not exist yet
+let getRestartData = null;
+try {
+  const mod = await import('../../utils/restartTracker.js');
+  getRestartData = mod.getRestartData ?? mod.default?.getRestartData ?? null;
+} catch {
+  // restartTracker not available yet — fallback to null
+}
+
 /**
  * GET / — Health check endpoint
  * Returns status, uptime, and Discord connection details.
- * Includes detailed memory usage only when a valid x-api-secret header is provided.
+ * Includes extended data only when a valid x-api-secret header is provided.
  */
-router.get('/', (req, res) => {
+router.get('/', async (req, res) => {
   const { client } = req.app.locals;
 
   // Defensive guard in case health check is hit before Discord login completes
@@ -38,6 +48,39 @@ router.get('/', (req, res) => {
       guilds: client.guilds.cache.size,
     };
     body.memory = process.memoryUsage();
+
+    body.system = {
+      platform: process.platform,
+      nodeVersion: process.version,
+      cpuUsage: process.cpuUsage(),
+    };
+
+    // Error counts from logs table
+    const now = new Date();
+    const oneHourAgo = new Date(now.getTime() - 60 * 60 * 1000);
+    const oneDayAgo = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+
+    const [hourResult, dayResult] = await Promise.all([
+      queryLogs({ level: 'error', since: oneHourAgo, limit: 1 }),
+      queryLogs({ level: 'error', since: oneDayAgo, limit: 1 }),
+    ]);
+
+    body.errors = {
+      lastHour: hourResult.total,
+      lastDay: dayResult.total,
+    };
+
+    // Restart data with graceful fallback
+    if (getRestartData) {
+      try {
+        const restartInfo = await getRestartData();
+        body.restarts = restartInfo;
+      } catch {
+        body.restarts = { total: 0, last: null };
+      }
+    } else {
+      body.restarts = { total: 0, last: null };
+    }
   }
 
   res.json(body);

src/api/server.js

@@ -9,6 +9,7 @@ import apiRouter from './index.js';
 import { rateLimit } from './middleware/rateLimit.js';
 import { stopAuthCleanup } from './routes/auth.js';
 import { stopGuildCacheCleanup } from './utils/discordApi.js';
+import { setupLogStream, stopLogStream } from './ws/logStream.js';
 
 /** @type {import('node:http').Server | null} */
 let server = null;
@@ -84,9 +85,11 @@ export function createApp(client, dbPool) {
  *
  * @param {import('discord.js').Client} client - Discord client instance
  * @param {import('pg').Pool | null} dbPool - PostgreSQL connection pool
+ * @param {Object} [options] - Additional options
+ * @param {import('../transports/websocket.js').WebSocketTransport} [options.wsTransport] - WebSocket transport for log streaming
  * @returns {Promise<import('node:http').Server>} The HTTP server instance
  */
-export async function startServer(client, dbPool) {
+export async function startServer(client, dbPool, options = {}) {
   if (server) {
     warn('startServer called while a server is already running — closing orphaned server');
     await stopServer();
@@ -108,6 +111,12 @@ export async function startServer(client, dbPool) {
   return new Promise((resolve, reject) => {
     server = app.listen(port, () => {
       info('API server started', { port });
+
+      // Attach WebSocket log stream if transport provided
+      if (options.wsTransport) {
+        setupLogStream(server, options.wsTransport);
+      }
+
       resolve(server);
     });
     server.once('error', (err) => {
@@ -124,6 +133,9 @@ export async function startServer(client, dbPool) {
  * @returns {Promise<void>}
  */
 export async function stopServer() {
+  // Stop WebSocket log stream before closing HTTP server
+  await stopLogStream();
+
   stopAuthCleanup();
   stopGuildCacheCleanup();