@selvakumaresra/specship 0.1.2 → 0.3.0

package/dist/server/routes/claude.js

@@ -15,6 +15,24 @@
  *   GET /api/claude/tips                     — rule-based tips engine output
  *   POST /api/claude/ingest                  — force a one-shot ingest pass
  */
+import { decodeProjectSlug } from '../ingest/index.js';
+/**
+ * Normalize a `?project=` filter value to the form stored in
+ * claude_sessions.project_path. The Sessions page (and any other UI
+ * surface that uses ProjectsService.projectQuery()) sends the directory
+ * SLUG that names the Claude Code transcript dir (e.g.
+ * `-Users-foo-projects-bar`), but the ingestor writes the DECODED path
+ * (e.g. `/Users/foo/projects/bar`) into project_path because that's the
+ * value the agent actually identifies the project by. Comparing slug
+ * against path always fails and the list comes back empty even though
+ * the rows are there — fix by decoding the slug form here.
+ *
+ * A path passed in directly (doesn't start with `-`) round-trips
+ * unchanged, so curl-by-path and the old behavior both keep working.
+ */
+function normalizeProjectFilter(input) {
+    return decodeProjectSlug(input);
+}
 const RANGE_WINDOW_MS = {
     today: 24 * 60 * 60 * 1000,
     week: 7 * 24 * 60 * 60 * 1000,
@@ -31,6 +49,18 @@ function rangeStart(key) {
         return 0;
     return Date.now() - RANGE_WINDOW_MS[key];
 }
+/**
+ * Bounds of the period immediately BEFORE the current range window — used for
+ * week-over-week (wowDelta) comparisons. For 'all' there's no prior period, so
+ * both bounds collapse to 0 and callers should treat the delta as 0.
+ */
+function priorWindow(key) {
+    if (key === 'all')
+        return { start: 0, end: 0 };
+    const w = RANGE_WINDOW_MS[key];
+    const end = Date.now() - w;
+    return { start: end - w, end };
+}
 /**
  * Get the internal SQLite handle off the DatabaseConnection so we can run
  * Claude-specific aggregate queries directly. SpecShip exposes this via
@@ -91,7 +121,7 @@ export async function registerClaudeRoutes(app) {
         let whereProject = '';
         if (req.query.project) {
             whereProject = ' AND project_path = ?';
-            params.push(req.query.project);
+            params.push(normalizeProjectFilter(req.query.project));
         }
         params.push(limit);
         const sessions = db.prepare(`
@@ -116,8 +146,216 @@ export async function registerClaudeRoutes(app) {
         const toolCalls = db.prepare(`
       SELECT * FROM claude_tool_calls WHERE session_id = ? ORDER BY ts ASC
     `).all(req.params.id);
+        // Per-prompt wall-clock duration: the gap from this prompt to the next one
+        // (last prompt runs to the session's end). Lets the UI show "how long did
+        // this turn take" without a separate per-event timeline.
+        const endedAt = session.ended_at ?? null;
+        prompts.forEach((p, i) => {
+            const next = prompts[i + 1];
+            const end = next ? next.ts : (endedAt ?? p.ts);
+            p.durationMs = Math.max(0, end - p.ts);
+        });
         return { session, prompts, toolCalls };
     });
+    /**
+     * SSE event stream for a single session — pushes new prompts and tool
+     * calls as the JSONL ingest watcher lands them, so the dashboard's
+     * Session Detail page can update without polling. Mirrors the shape used
+     * by /api/workflows/runs/:id/events.
+     *
+     * Polling cadence inside the loop is 500 ms — fast enough that the
+     * end-to-end "user hit Enter in Claude Code → prompt visible in
+     * dashboard" latency stays well under one second (300 ms watcher
+     * debounce + ≤50 ms ingest + ≤500 ms poll). Heartbeat every 15 s
+     * keeps idle connections alive past any proxy or browser tab-throttle
+     * cutoff.
+     *
+     * The client (LiveSessionTail in session-detail.ts) doesn't merge events
+     * incrementally — it just calls resource.refetch() on every event since
+     * the detail endpoint is local + cheap. Server-side, that means we only
+     * need to push enough info for the client to know "something changed"
+     * (id + ts), not the full row payloads. We send the full row anyway so
+     * a future client could merge incrementally without an API change.
+     */
+    app.get('/api/claude/session/:id/events', async (req, reply) => {
+        const cg = requirePrimary(reply);
+        if (!cg)
+            return;
+        const db = getDb(cg);
+        const sessionId = req.params.id;
+        // Confirm the session exists before opening the stream — saves a
+        // doomed connection from polling forever against a typo.
+        const sessionRow = db.prepare('SELECT id FROM claude_sessions WHERE id = ?').get(sessionId);
+        if (!sessionRow) {
+            return reply.code(404).send({ error: 'session not found' });
+        }
+        // Resume points — clients can pick up after a disconnect without
+        // re-receiving every prompt. Defaults to "now" so an opening client
+        // only sees future events.
+        let lastPromptTs = parseInt(req.query.sincePromptTs ?? '0', 10);
+        let lastToolTs = parseInt(req.query.sinceToolTs ?? '0', 10);
+        if (!lastPromptTs || Number.isNaN(lastPromptTs)) {
+            const row = db.prepare('SELECT MAX(ts) as m FROM claude_prompts WHERE session_id = ?').get(sessionId);
+            lastPromptTs = row?.m ?? 0;
+        }
+        if (!lastToolTs || Number.isNaN(lastToolTs)) {
+            const row = db.prepare('SELECT MAX(ts) as m FROM claude_tool_calls WHERE session_id = ?').get(sessionId);
+            lastToolTs = row?.m ?? 0;
+        }
+        reply.raw.setHeader('Content-Type', 'text/event-stream');
+        reply.raw.setHeader('Cache-Control', 'no-cache');
+        reply.raw.setHeader('Connection', 'keep-alive');
+        reply.raw.setHeader('X-Accel-Buffering', 'no'); // nginx-friendly
+        reply.raw.flushHeaders();
+        // Initial snapshot — gives the client a clean baseline (so it knows
+        // SSE is wired up even before any new event fires) and the cursor
+        // positions it should resume from on reconnect.
+        reply.raw.write(`event: snapshot\ndata: ${JSON.stringify({ sessionId, lastPromptTs, lastToolTs })}\n\n`);
+        let closed = false;
+        req.raw.on('close', () => { closed = true; });
+        const newPromptsStmt = db.prepare('SELECT * FROM claude_prompts WHERE session_id = ? AND ts > ? ORDER BY ts ASC');
+        const newToolsStmt = db.prepare('SELECT * FROM claude_tool_calls WHERE session_id = ? AND ts > ? ORDER BY ts ASC');
+        let lastHeartbeat = Date.now();
+        const tick = () => {
+            if (closed)
+                return;
+            try {
+                const freshPrompts = newPromptsStmt.all(sessionId, lastPromptTs);
+                for (const p of freshPrompts) {
+                    reply.raw.write(`event: prompt_added\ndata: ${JSON.stringify(p)}\n\n`);
+                    if (p.ts > lastPromptTs)
+                        lastPromptTs = p.ts;
+                }
+                const freshTools = newToolsStmt.all(sessionId, lastToolTs);
+                for (const t of freshTools) {
+                    reply.raw.write(`event: tool_call_added\ndata: ${JSON.stringify(t)}\n\n`);
+                    if (t.ts > lastToolTs)
+                        lastToolTs = t.ts;
+                }
+                // Heartbeat every 15 s — keeps proxies / browser tab throttles
+                // from killing an otherwise-idle connection.
+                const now = Date.now();
+                if (now - lastHeartbeat >= 15_000) {
+                    reply.raw.write(`: keepalive ${now}\n\n`);
+                    lastHeartbeat = now;
+                }
+            }
+            catch (err) {
+                // Surface DB errors to the client as a named event and end the
+                // stream — the client's onError handler flips to polling.
+                reply.raw.write(`event: stream_error\ndata: ${JSON.stringify({ message: err instanceof Error ? err.message : String(err) })}\n\n`);
+                reply.raw.end();
+                closed = true;
+                return;
+            }
+            setTimeout(tick, 500);
+        };
+        void tick();
+    });
+    /**
+     * Session-level aggregation for the Session Detail "Session summary" panel.
+     * Three things callers can't cheaply derive client-side from the per-prompt
+     * list: tool usage rolled up by name, files touched across all turns, and
+     * slash-command / skill invocation counts (which require either a regex
+     * over every prompt's text or json_extract over every Skill tool input).
+     * Computed once per session-detail page load (and after refresh) — cheap
+     * enough to recompute on every call, no caching.
+     */
+    app.get('/api/claude/session/:id/summary', async (req, reply) => {
+        const cg = requirePrimary(reply);
+        if (!cg)
+            return;
+        const db = getDb(cg);
+        const sessionId = req.params.id;
+        const session = db.prepare('SELECT id, started_at, ended_at FROM claude_sessions WHERE id = ?').get(sessionId);
+        if (!session)
+            return reply.code(404).send({ error: 'session not found' });
+        // Tools used in this session, rolled up by name. Mirrors the heatmap
+        // tool query but scoped to one session, so the panel can answer "what
+        // did Claude DO in this session" at a glance.
+        const byTool = db.prepare(`
+      SELECT tool_name as name, COUNT(*) as calls, COALESCE(SUM(result_length), 0) as totalBytes
+      FROM claude_tool_calls
+      WHERE session_id = ?
+      GROUP BY tool_name
+      ORDER BY calls DESC
+    `).all(sessionId);
+        // Models used. Most sessions stay on one model but sidechains can fan
+        // out to Haiku, so this surfaces multi-model spend that the session-level
+        // last_model column hides.
+        const byModel = db.prepare(`
+      SELECT model, COUNT(*) as prompts, COALESCE(SUM(cost_usd), 0) as cost
+      FROM claude_prompts
+      WHERE session_id = ? AND model IS NOT NULL
+      GROUP BY model
+      ORDER BY cost DESC
+    `).all(sessionId);
+        // Files touched via Read/Edit/Write/NotebookEdit. input_summary IS the
+        // file path for those tools (set in the ingestor's parser). Group by
+        // path, count ops, also record which tool last touched it so the UI
+        // can show a "last op" hint (Read vs Edit).
+        const filesTouched = db.prepare(`
+      SELECT input_summary as path, COUNT(*) as ops,
+             (SELECT tool_name FROM claude_tool_calls AS inner_tc
+                WHERE inner_tc.session_id = tc.session_id
+                  AND inner_tc.input_summary = tc.input_summary
+                ORDER BY inner_tc.ts DESC LIMIT 1) as lastOp
+      FROM claude_tool_calls AS tc
+      WHERE tc.session_id = ?
+        AND tc.tool_name IN ('Read','Edit','Write','NotebookEdit','MultiEdit')
+        AND tc.input_summary != ''
+      GROUP BY tc.input_summary
+      ORDER BY ops DESC
+      LIMIT 30
+    `).all(sessionId);
+        // Skills invoked via the Skill tool. The ingestor stashes the
+        // JSON-serialized input under input_summary, so json_extract pulls the
+        // skill name straight out without needing the v7 input_json column to
+        // be backfilled.
+        const skills = db.prepare(`
+      SELECT
+        COALESCE(json_extract(input_summary, '$.skill'), json_extract(input_summary, '$.skill_name'), 'unknown') as name,
+        COUNT(*) as count
+      FROM claude_tool_calls
+      WHERE session_id = ? AND tool_name = 'Skill'
+      GROUP BY name
+      ORDER BY count DESC
+    `).all(sessionId);
+        // Slash commands invoked. Claude Code wraps each one in a
+        // <command-name>/foo</command-name> tag in the user-prompt text.
+        // Pull every prompt that has that tag and regex it client-side here
+        // (SQLite has no built-in regex). Cheap — most sessions have <50.
+        const taggedPrompts = db.prepare(`
+      SELECT text FROM claude_prompts WHERE session_id = ? AND text LIKE '%<command-name>%'
+    `).all(sessionId);
+        const cmdCounts = new Map();
+        const cmdRe = /<command-name>([^<]+)<\/command-name>/g;
+        for (const { text } of taggedPrompts) {
+            if (!text)
+                continue;
+            for (const m of text.matchAll(cmdRe)) {
+                const raw = m[1]?.trim();
+                if (!raw)
+                    continue;
+                cmdCounts.set(raw, (cmdCounts.get(raw) ?? 0) + 1);
+            }
+        }
+        const slashCommands = Array.from(cmdCounts.entries())
+            .map(([name, count]) => ({ name, count }))
+            .sort((a, b) => b.count - a.count);
+        const durationMs = session.started_at && session.ended_at
+            ? Math.max(0, session.ended_at - session.started_at)
+            : 0;
+        return {
+            sessionId,
+            byTool,
+            byModel,
+            slashCommands,
+            skills,
+            filesTouched,
+            durationMs,
+        };
+    });
     app.get('/api/claude/heatmap', async (req, reply) => {
         const cg = requirePrimary(reply);
         if (!cg)
@@ -133,6 +371,28 @@ export async function registerClaudeRoutes(app) {
       ORDER BY calls DESC
       LIMIT 100
     `).all(since);
+        // Per-file 7-day call trend — one sparkline (oldest→newest) per file cell.
+        // Always a fixed 7-day window, independent of `range`, so the trend reads
+        // consistently regardless of the heatmap's selected window.
+        const dayMs = 24 * 60 * 60 * 1000;
+        const trend7Start = Math.floor(Date.now() / dayMs) * dayMs - 6 * dayMs;
+        const trendRows = db.prepare(`
+      SELECT input_summary as path, CAST((ts - ?) / ? AS INTEGER) as bucket, COUNT(*) as calls
+      FROM claude_tool_calls
+      WHERE ts >= ? AND tool_name IN ('Read','Edit','Write','NotebookEdit') AND input_summary != ''
+      GROUP BY input_summary, bucket
+    `).all(trend7Start, dayMs, trend7Start);
+        const trendByPath = new Map();
+        for (const r of trendRows) {
+            if (r.bucket < 0 || r.bucket > 6)
+                continue;
+            const arr = trendByPath.get(r.path) ?? [0, 0, 0, 0, 0, 0, 0];
+            arr[r.bucket] = r.calls;
+            trendByPath.set(r.path, arr);
+        }
+        for (const f of files) {
+            f.trend = trendByPath.get(f.path) ?? [0, 0, 0, 0, 0, 0, 0];
+        }
         // Tools heatmap.
         const tools = db.prepare(`
       SELECT tool_name as name, COUNT(*) as calls, SUM(result_length) as resultBytes
@@ -302,6 +562,24 @@ export async function registerClaudeRoutes(app) {
         // Use Opus 4-7 input ($15/M) as a generous upper bound — the UI shows
         // this as an approximation.
         const dollarsSaved = ((agg.cr ?? 0) / 1_000_000) * 15 * 0.9;
+        // Week-over-week reuse delta: current read-rate minus the prior equal-length
+        // window's read-rate. Fractional (e.g. 0.06 → "+6%" in the UI). Zero for
+        // 'all' (no prior period) or when there's no prior-window data to compare.
+        const prior = priorWindow(rangeKey(req.query.range));
+        let wowDelta = 0;
+        if (prior.end > prior.start) {
+            const pAgg = db.prepare(`
+        SELECT
+          COALESCE(SUM(total_input_tokens), 0) as inp,
+          COALESCE(SUM(total_cache_creation_tokens), 0) as cw,
+          COALESCE(SUM(total_cache_read_tokens), 0) as cr
+        FROM claude_sessions
+        WHERE started_at >= ? AND started_at < ?
+      `).get(prior.start, prior.end);
+            const pTotal = (pAgg.inp ?? 0) + (pAgg.cw ?? 0) + (pAgg.cr ?? 0);
+            if (pTotal > 0)
+                wowDelta = readRate - pAgg.cr / pTotal;
+        }
         return {
             readRate,
             creationTokens: agg.cw ?? 0,
@@ -310,9 +588,7 @@ export async function registerClaudeRoutes(app) {
             outputTokens: agg.out ?? 0,
             totalCost: agg.cost ?? 0,
             dollarsSaved,
-            // wowDelta would need historical snapshotting; placeholder until we
-            // add a rolling-window aggregate table. UI shows 0% with no arrow.
-            wowDelta: 0,
+            wowDelta,
         };
     });
     app.get('/api/claude/costs', async (req, reply) => {
@@ -322,6 +598,16 @@ export async function registerClaudeRoutes(app) {
         const db = getDb(cg);
         const since = rangeStart(rangeKey(req.query.range));
         const total = db.prepare(`SELECT SUM(total_cost_usd) as t FROM claude_sessions WHERE started_at >= ?`).get(since);
+        // Week-over-week spend delta: fractional change in total cost vs the prior
+        // equal-length window (e.g. -0.08 → "-8%"). Zero for 'all' or no prior data.
+        const prior = priorWindow(rangeKey(req.query.range));
+        let wowDelta = 0;
+        if (prior.end > prior.start) {
+            const pTotal = db.prepare(`SELECT SUM(total_cost_usd) as t FROM claude_sessions WHERE started_at >= ? AND started_at < ?`).get(prior.start, prior.end);
+            const pt = pTotal.t ?? 0;
+            if (pt > 0)
+                wowDelta = ((total.t ?? 0) - pt) / pt;
+        }
         // Top prompts by cost.
         const topPrompts = db.prepare(`
       SELECT id, session_id, substr(text, 1, 200) as text, model, cost_usd,
@@ -359,7 +645,74 @@ export async function registerClaudeRoutes(app) {
       GROUP BY model
       ORDER BY cost DESC
     `).all(since);
-        return { total: total.t ?? 0, topPrompts, series: dense, byModel };
+        return { total: total.t ?? 0, topPrompts, series: dense, byModel, wowDelta };
+    });
+    /**
+     * GET /api/claude/stats?range= — the four dashboard stat tiles, each with a
+     * value, a fractional week-over-week delta (vs the prior equal-length window)
+     * and a 7-day sparkline series (oldest→newest). Drift is a live graph metric
+     * with no history, so it returns value-only.
+     */
+    app.get('/api/claude/stats', async (req, reply) => {
+        const cg = requirePrimary(reply);
+        if (!cg)
+            return;
+        const db = getDb(cg);
+        const rkey = rangeKey(req.query.range);
+        const since = rangeStart(rkey);
+        const prior = priorWindow(rkey);
+        const dayMs = 24 * 60 * 60 * 1000;
+        const d7Start = Math.floor(Date.now() / dayMs) * dayMs - 6 * dayMs;
+        const dense7 = (rows) => {
+            const a = [0, 0, 0, 0, 0, 0, 0];
+            for (const r of rows)
+                if (r.bucket >= 0 && r.bucket <= 6)
+                    a[r.bucket] = r.v;
+            return a;
+        };
+        const countSince = (sql, ...p) => db.prepare(sql).get(...p).c ?? 0;
+        // --- Tool calls ---
+        const tcTotal = countSince(`SELECT COUNT(*) c FROM claude_tool_calls WHERE ts >= ?`, since);
+        const tcPrior = prior.end > prior.start
+            ? countSince(`SELECT COUNT(*) c FROM claude_tool_calls WHERE ts >= ? AND ts < ?`, prior.start, prior.end)
+            : 0;
+        const tcSeries = db.prepare(`SELECT CAST((ts - ?) / ? AS INTEGER) as bucket, COUNT(*) as v FROM claude_tool_calls WHERE ts >= ? GROUP BY bucket`).all(d7Start, dayMs, d7Start);
+        const toolCalls = { value: tcTotal, delta: tcPrior > 0 ? (tcTotal - tcPrior) / tcPrior : 0, series: dense7(tcSeries) };
+        // --- Subagent spend share (by cost) ---
+        const subPctOf = (start, end) => {
+            const where = end == null ? `ts >= ?` : `ts >= ? AND ts < ?`;
+            const args = end == null ? [start] : [start, end];
+            const rows = db.prepare(`SELECT is_sidechain as side, COALESCE(SUM(cost_usd), 0) as cost FROM claude_prompts WHERE ${where} GROUP BY is_sidechain`).all(...args);
+            const sub = rows.find((r) => r.side === 1)?.cost ?? 0;
+            const tot = rows.reduce((a, r) => a + (r.cost ?? 0), 0);
+            return tot > 0 ? sub / tot : 0;
+        };
+        const subPct = subPctOf(since, null);
+        const subPctPrior = prior.end > prior.start ? subPctOf(prior.start, prior.end) : 0;
+        const saDaily = db.prepare(`
+      SELECT CAST((ts - ?) / ? AS INTEGER) as bucket,
+             SUM(CASE WHEN is_sidechain = 1 THEN cost_usd ELSE 0 END) as sub,
+             SUM(cost_usd) as tot
+      FROM claude_prompts WHERE ts >= ? GROUP BY bucket
+    `).all(d7Start, dayMs, d7Start);
+        const saSeries = [0, 0, 0, 0, 0, 0, 0];
+        for (const r of saDaily)
+            if (r.bucket >= 0 && r.bucket <= 6)
+                saSeries[r.bucket] = r.tot > 0 ? Math.round((r.sub / r.tot) * 100) : 0;
+        const subagentPct = { value: Math.round(subPct * 100), delta: subPct - subPctPrior, series: saSeries };
+        // --- Last session cost (delta vs previous session, spark of recent sessions) ---
+        const recent = db.prepare(`SELECT total_cost_usd as cost FROM claude_sessions ORDER BY started_at DESC LIMIT 10`).all();
+        const lastCost = recent[0]?.cost ?? 0;
+        const prevCost = recent[1]?.cost ?? 0;
+        const lastSessionCost = {
+            value: lastCost,
+            delta: prevCost > 0 ? (lastCost - prevCost) / prevCost : 0,
+            series: recent.map((r) => r.cost ?? 0).reverse(),
+        };
+        // --- Drift (live graph count, no time series) ---
+        const driftCount = cg.getSpecQueries().getLinksByState(['drifted', 'broken', 'orphaned']).length;
+        const drift = { value: driftCount, delta: 0, series: [] };
+        return { lastSessionCost, toolCalls, subagentPct, drift };
     });
     app.get('/api/claude/compare', async (_req, reply) => {
         const cg = requirePrimary(reply);
@@ -381,7 +734,42 @@ export async function registerClaudeRoutes(app) {
       GROUP BY p.path
       ORDER BY cost DESC
     `).all();
-        return { projects: rows };
+        // Per-model cost split per project (drives the stacked bars).
+        const modelRows = db.prepare(`
+      SELECT s.project_path as path, p.model as model, COALESCE(SUM(p.cost_usd), 0) as cost
+      FROM claude_prompts p
+      JOIN claude_sessions s ON s.id = p.session_id
+      WHERE p.model IS NOT NULL
+      GROUP BY s.project_path, p.model
+    `).all();
+        const byModelByPath = new Map();
+        for (const r of modelRows) {
+            const arr = byModelByPath.get(r.path) ?? [];
+            arr.push({ model: r.model, cost: r.cost });
+            byModelByPath.set(r.path, arr);
+        }
+        // Top tools per project (top 4 by call count).
+        const toolRows = db.prepare(`
+      SELECT s.project_path as path, t.tool_name as name, COUNT(*) as calls
+      FROM claude_tool_calls t
+      JOIN claude_sessions s ON s.id = t.session_id
+      GROUP BY s.project_path, t.tool_name
+    `).all();
+        const toolsByPath = new Map();
+        for (const r of toolRows) {
+            const arr = toolsByPath.get(r.path) ?? [];
+            arr.push({ name: r.name, calls: r.calls });
+            toolsByPath.set(r.path, arr);
+        }
+        const projects = rows.map((p) => ({
+            ...p,
+            byModel: (byModelByPath.get(p.path) ?? []).sort((a, b) => b.cost - a.cost),
+            topTools: (toolsByPath.get(p.path) ?? [])
+                .sort((a, b) => b.calls - a.calls)
+                .slice(0, 4)
+                .map((t) => t.name),
+        }));
+        return { projects };
     });
     /**
      * Rule-based tips engine. Each rule is a SQL query that finds a wasteful

package/dist/server/routes/graph.js

@@ -19,6 +19,15 @@ async function resolveCg(app, req, reply) {
     }
     return cg;
 }
+/** Dig the raw SQLite handle off a SpecShip instance (same shape as routes/claude.ts). */
+function getDb(cg) {
+    const anyCg = cg;
+    if (anyCg.db?.getDb)
+        return anyCg.db.getDb();
+    if (anyCg.queries?.db)
+        return anyCg.queries.db;
+    throw new Error('specship DB handle not accessible from server context');
+}
 export async function registerGraphRoutes(app) {
     app.get('/api/graph/stats', async (req, reply) => {
         const cg = await resolveCg(app, req, reply);
@@ -146,4 +155,57 @@ export async function registerGraphRoutes(app) {
             return;
         return { files: cg.getFiles() };
     });
+    /**
+     * GET /api/graph/health — feeds the Graph overview panel:
+     *   - linkHealth: spec-link counts per state (verified/drifted/broken/orphaned/…)
+     *   - edgeKinds:  edge counts grouped into calls / implements-documents / tests
+     *   - hubs:       the most-connected nodes (by total degree), for the "Most connected" list
+     */
+    app.get('/api/graph/health', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        // Spec-link health — count by state off the spec_links table.
+        const linkHealth = {};
+        for (const l of cg.getSpecQueries().getAllLinks()) {
+            linkHealth[l.state] = (linkHealth[l.state] ?? 0) + 1;
+        }
+        const db = getDb(cg);
+        // Edge kinds — bucket by the node kinds the edge connects, mirroring the
+        // design's "calls / implements / tests" legend. spec endpoints → implements,
+        // test endpoints → tests, everything else → calls.
+        const edgeKinds = db.prepare(`
+      SELECT
+        CASE
+          WHEN ns.kind = 'spec' OR nt.kind = 'spec' THEN 'implements'
+          WHEN ns.kind = 'test' OR nt.kind = 'test' THEN 'tests'
+          ELSE 'calls'
+        END as bucket,
+        COUNT(*) as count
+      FROM edges e
+      JOIN nodes ns ON ns.id = e.source
+      JOIN nodes nt ON nt.id = e.target
+      GROUP BY bucket
+    `).all();
+        const edgeKindMap = { calls: 0, implements: 0, tests: 0 };
+        for (const r of edgeKinds)
+            edgeKindMap[r.bucket] = r.count;
+        // Synthesized (heuristic) edge count — dashed in the legend.
+        const synth = db.prepare(`SELECT COUNT(*) as c FROM edges WHERE provenance = 'heuristic'`).get();
+        edgeKindMap['synth'] = synth.c ?? 0;
+        // Most-connected hubs — total degree (in + out) per node, top 8.
+        const hubs = db.prepare(`
+      SELECT n.id, n.name, n.kind, n.file_path as filePath, deg.degree
+      FROM (
+        SELECT node, COUNT(*) as degree FROM (
+          SELECT source as node FROM edges
+          UNION ALL
+          SELECT target as node FROM edges
+        ) GROUP BY node ORDER BY degree DESC LIMIT 8
+      ) deg
+      JOIN nodes n ON n.id = deg.node
+      ORDER BY deg.degree DESC
+    `).all();
+        return { linkHealth, edgeKinds: edgeKindMap, hubs };
+    });
 }