Implement Feature #7: Health Check API

New Module: health-check.ts
- /health: Returns system health status (uptime, memory, groups)
- /ready: Returns readiness for traffic
- /metrics: Prometheus-compatible metrics format

Config (config.ts):
- HEALTH_CHECK.ENABLED: Toggle via HEALTH_CHECK_ENABLED env
- HEALTH_CHECK.PORT: Default 8080

Integration (index.ts):
- Started in main() after database init
- Stopped gracefully on SIGINT/SIGTERM
- Added SIGTERM handler for container orchestration

This enables monitoring via external systems like
Kubernetes, Docker healthchecks, or Prometheus.

Author: Rlin1027

src/config.ts

@@ -47,6 +47,16 @@ export const CONTAINER_MAX_OUTPUT_SIZE = parseInt(
 ); // 10MB default
 export const IPC_POLL_INTERVAL = 1000;
 
+/**
+ * Health check HTTP server configuration
+ */
+export const HEALTH_CHECK = {
+  /** Enable health check HTTP server */
+  ENABLED: process.env.HEALTH_CHECK_ENABLED !== 'false',
+  /** Port for health check server */
+  PORT: parseInt(process.env.HEALTH_CHECK_PORT || '8080', 10),
+} as const;
+
 function escapeRegex(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

src/health-check.ts

@@ -0,0 +1,146 @@
+/**
+ * Health Check HTTP Server
+ * 
+ * Provides /health and /ready endpoints for container orchestration
+ * and external monitoring systems.
+ */
+
+import { createServer, IncomingMessage, ServerResponse } from 'http';
+import { HEALTH_CHECK } from './config.js';
+import { logger } from './logger.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface HealthStatus {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    uptime: number;
+    memory: {
+        heapUsed: number;
+        heapTotal: number;
+        rss: number;
+    };
+    groups: number;
+    version: string;
+    timestamp: string;
+}
+
+// ============================================================================
+// State (injected at startup)
+// ============================================================================
+
+let getGroupCount: () => number = () => 0;
+let getActiveContainers: () => number = () => 0;
+
+export function setHealthCheckDependencies(deps: {
+    getGroupCount: () => number;
+    getActiveContainers?: () => number;
+}): void {
+    getGroupCount = deps.getGroupCount;
+    if (deps.getActiveContainers) {
+        getActiveContainers = deps.getActiveContainers;
+    }
+}
+
+// ============================================================================
+// Health Status
+// ============================================================================
+
+function getHealthStatus(): HealthStatus {
+    const memUsage = process.memoryUsage();
+
+    return {
+        status: 'healthy',
+        uptime: process.uptime(),
+        memory: {
+            heapUsed: Math.round(memUsage.heapUsed / 1024 / 1024),
+            heapTotal: Math.round(memUsage.heapTotal / 1024 / 1024),
+            rss: Math.round(memUsage.rss / 1024 / 1024),
+        },
+        groups: getGroupCount(),
+        version: process.env.npm_package_version || '1.0.0',
+        timestamp: new Date().toISOString(),
+    };
+}
+
+// ============================================================================
+// HTTP Server
+// ============================================================================
+
+function handleRequest(req: IncomingMessage, res: ServerResponse): void {
+    const url = req.url || '/';
+
+    // CORS headers for browser access
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Content-Type', 'application/json');
+
+    if (url === '/health' || url === '/healthz') {
+        const health = getHealthStatus();
+        res.statusCode = health.status === 'healthy' ? 200 : 503;
+        res.end(JSON.stringify(health, null, 2));
+    } else if (url === '/ready' || url === '/readyz') {
+        // Readiness check - are we ready to accept traffic?
+        const ready = getGroupCount() > 0;
+        res.statusCode = ready ? 200 : 503;
+        res.end(JSON.stringify({
+            ready,
+            groups: getGroupCount(),
+            activeContainers: getActiveContainers(),
+        }));
+    } else if (url === '/metrics') {
+        // Prometheus-style metrics
+        const health = getHealthStatus();
+        res.setHeader('Content-Type', 'text/plain');
+        res.end(`# HELP nanogemclaw_uptime_seconds Application uptime
+# TYPE nanogemclaw_uptime_seconds gauge
+nanogemclaw_uptime_seconds ${health.uptime.toFixed(0)}
+
+# HELP nanogemclaw_memory_heap_bytes Heap memory used
+# TYPE nanogemclaw_memory_heap_bytes gauge
+nanogemclaw_memory_heap_bytes ${health.memory.heapUsed * 1024 * 1024}
+
+# HELP nanogemclaw_groups_total Number of registered groups
+# TYPE nanogemclaw_groups_total gauge
+nanogemclaw_groups_total ${health.groups}
+`);
+    } else {
+        res.statusCode = 404;
+        res.end(JSON.stringify({ error: 'Not found' }));
+    }
+}
+
+let server: ReturnType<typeof createServer> | null = null;
+
+export function startHealthCheckServer(): void {
+    if (!HEALTH_CHECK.ENABLED) {
+        logger.info('Health check server disabled');
+        return;
+    }
+
+    server = createServer(handleRequest);
+
+    server.listen(HEALTH_CHECK.PORT, () => {
+        logger.info(
+            { port: HEALTH_CHECK.PORT },
+            'Health check server started',
+        );
+    });
+
+    server.on('error', (err) => {
+        logger.error({ err }, 'Health check server error');
+    });
+}
+
+export function stopHealthCheckServer(): Promise<void> {
+    return new Promise((resolve) => {
+        if (server) {
+            server.close(() => {
+                logger.info('Health check server stopped');
+                resolve();
+            });
+        } else {
+            resolve();
+        }
+    });
+}

src/index.ts

@@ -1028,6 +1028,13 @@ async function main(): Promise<void> {
   initDatabase();
   loadState();
 
+  // Start health check server
+  const { setHealthCheckDependencies, startHealthCheckServer } = await import('./health-check.js');
+  setHealthCheckDependencies({
+    getGroupCount: () => Object.keys(registeredGroups).length,
+  });
+  startHealthCheckServer();
+
   // Connect to Telegram
   await connectTelegram();
 }
@@ -1041,6 +1048,8 @@ main().catch((err) => {
 process.on('SIGINT', async () => {
   console.log('\nShutting down gracefully...');
   try {
+    const { stopHealthCheckServer } = await import('./health-check.js');
+    await stopHealthCheckServer();
     await bot?.stopPolling();
     saveState();
     closeDatabase();
@@ -1054,6 +1063,8 @@ process.on('SIGINT', async () => {
 process.on('SIGTERM', async () => {
   console.log('Received SIGTERM, shutting down...');
   try {
+    const { stopHealthCheckServer } = await import('./health-check.js');
+    await stopHealthCheckServer();
     await bot?.stopPolling();
     saveState();
     closeDatabase();