feat(gain): --web flag — local dashboard server

[thehoff]

Background

The natural extension for contextcrawler analytics is a local web UI that renders the data already in history.db instead of (or alongside) the CLI text output.

Pairs naturally with #158 (gain --insights) — the insights become dashboard cards.

Problem

gain, gain --weak-filters, gain --insights, gain --history all return text or JSON to the terminal. For glanceable per-day / per-tool / per-boundary trend views, a web dashboard is the right surface:

• Daily / weekly savings charts (already have the data per the get_by_day query)
• Per-tool leaderboard with drill-down to recent worst invocations
• Release-boundary timeline (when did v0.1.10 land, how did ls savings change before/after — already exposed by PR feat(gain): release-boundary slicing for --weak-filters #150 substrate)
• Insight cards (feat(gain): --insights mode — surface patterns from the tracking DB #158 patterns rendered as dismissable tiles)
• Parse-failure recovery rate over time
• Filter quality vs target (per-command targets defined in CLAUDE.md)

Proposed Design (clean-room)

New flag: contextcrawler gain --web [--port <N>] [--no-browser].

contextcrawler gain --web              # boots server on a free port + opens browser
contextcrawler gain --web --port 8765  # explicit port
contextcrawler gain --web --no-browser # no auto-open (for ssh/remote use)

Behaviour:

1. Bind a tiny HTTP server (tiny_http crate, ~300KB; or hyper with rustls if we want HTTPS later) on the chosen port
2. Serve a single-page HTML app from embedded assets (rust-embed pattern)
3. Page hits JSON endpoints backed by the existing Tracker query functions:
   • /api/summary → get_summary_filtered
   • /api/by-day → get_by_day
   • /api/weak-filters?since=<iso> → get_weak_filters
   • /api/insights → feat(gain): --insights mode — surface patterns from the tracking DB #158 results
   • /api/boundaries → latest_boundary_timestamp + list of all release boundaries
   • /api/failures → get_parse_failure_summary
4. Auto-shutdown after 1h of inactivity (don't leave a server running)
5. Read-only — no DB writes from the web UI. No auth (binds to 127.0.0.1 by default)

Frontend: minimal vanilla JS + a small chart lib (Chart.js inlined, or roll a 50-line SVG sparkline). No build pipeline; one self-contained HTML file embedded via include_str!. Left-side menu, scalable card layout.

Why now

• Requested for the v0.1.x roadmap (2026-05-23)
• Data is already in the DB; this is purely a presentation layer
• Pairs with feat(gain): --insights mode — surface patterns from the tracking DB #158 (insights) — both surfaces share the same query funcs

Effort

M (1 week)

• HTTP server + asset embedding: 1 day
• 6 API endpoints: 1 day
• Frontend HTML + JS + charts: 2-3 days
• Tests (route handlers, JSON shape, inactivity shutdown): 1 day
• Doc + screenshot in README: half day

Out of scope (v1)

• Auth / HTTPS / cross-machine access (lab-only profile, 127.0.0.1 binding only)
• Persistent server / daemon mode (autoshutdown handles this)
• Realtime updates / SSE / WebSockets — polling is fine for a single-user local dashboard
• Cross-machine federation (e.g. aggregating multiple developers' DBs)
• Theme customisation
• Auth integration with any external dashboard host (potential future hook — left-side menu plug-in)

Dependencies

• Soft dep on feat(gain): --insights mode — surface patterns from the tracking DB #158 (gain --insights): the insights API endpoint is most useful when insights exist. Can build the dashboard first with placeholder content and wire feat(gain): --insights mode — surface patterns from the tracking DB #158 results in when they land.

[thehoff]

Backlog note: the original implementation PR #178 was closed (conflicted with develop after the 0.4.0 lib pivot). This issue + the pane issues (#171/#172/#175/#176/#177) are kept as the roadmap to rebuild the dashboard fresh when revisited.

[thehoff]

Status 2026-08-19: shipped in v0.5.0 via feat/gain-web-162-rebuild (0015b055 + post-release fixes through 90db05da). Endpoints /api/{summary,by-day,weak-filters,failures,boundaries,insights} live, 127.0.0.1-only, 1h idle auto-shutdown.

PR #178 (combined 162/171/172) was closed without merge — only #162 made it into develop. #171/#172 stay open as separate items.

Suggest: close this one.