fix(docker): add dedicated health endpoint for container healthcheck (#1147) (#1355)

docker-compose.yaml

@@ -19,7 +19,7 @@ services:
       - ${WORKSPACE_DIR:-./workspace}:/workspace:ro
     restart: unless-stopped
     healthcheck:
-      test: ['CMD', 'curl', '-fsSI', 'http://localhost:4747/api/heartbeat']
+      test: ['CMD', 'curl', '-f', 'http://localhost:4747/api/health']
       interval: 30s
       timeout: 5s
       retries: 3

gitnexus/src/server/api.ts

@@ -183,6 +183,7 @@ a.ext:hover{text-decoration:underline}
   <div class="section-title">Endpoints</div>
   <p class="endpoint"><a href="/api/info">/api/info</a> <span style="color:#5a5a70">— Server version &amp; context</span></p>
   <p class="endpoint"><a href="/api/repos">/api/repos</a> <span style="color:#5a5a70">— Indexed repositories</span></p>
+  <p class="endpoint"><code>/api/health</code> <span style="color:#5a5a70">— Docker/orchestrator healthcheck</span></p>
   <p class="endpoint"><code>/api/heartbeat</code> <span style="color:#5a5a70">— SSE heartbeat</span></p>
   <p class="endpoint"><code>/api/graph</code> <code>/api/query</code> <code>/api/search</code> <span style="color:#5a5a70">— Data</span></p>
   <p class="endpoint"><code>/api/mcp</code> <span style="color:#5a5a70">— MCP over StreamableHTTP</span></p>
@@ -777,6 +778,13 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
     return found;
   };
 
+  // Lightweight healthcheck for Docker/orchestrator probes (#1147).
+  // Returns immediately so container managers do not confuse a long-lived
+  // SSE stream with an unhealthy server.
+  app.get('/api/health', (_req, res) => {
+    res.json({ status: 'ok' });
+  });
+
   // SSE heartbeat — clients connect to detect server liveness instantly.
   // When the server shuts down, the TCP connection drops and the client's
   // EventSource fires onerror immediately (no polling delay).

gitnexus/test/unit/rate-limit.test.ts

@@ -242,6 +242,10 @@ describe('production routes — rate-limit middleware wiring', () => {
     expect(apiSource).toMatch(/app\.get\(SPA_FALLBACK_REGEX,\s*createRouteLimiter\(/);
   });
 
+  it('GET /api/health is registered (Docker healthcheck, #1147)', () => {
+    expect(apiSource).toMatch(/app\.get\('\/api\/health',\s*\(_req,\s*res\)\s*=>/);
+  });
+
   it('createServer wires trust proxy to loopback/linklocal/uniquelocal', () => {
     expect(apiSource).toMatch(
       /app\.set\(\s*'trust proxy'\s*,\s*'loopback,\s*linklocal,\s*uniquelocal'\s*\)/,