Skip to content

docs(qa): Web UI UX audit — ranked findings (ux-audit epic) - #1046

Merged
Dumbris merged 2 commits into
mainfrom
audit/ux-webui-sweep
Aug 26, 2026
Merged

Dumbris merged 2 commits into
mainfrom
audit/ux-webui-sweep

Conversation

@Dumbris

@Dumbris Dumbris commented Aug 25, 2026

Copy link
Copy Markdown
Member

Heuristic + live-instance UX audit of the Web UI for the ux-audit epic (P0, gates action-log-transparency, analytics-default-landing, remote-access-tunnel).

Every routed view walked in light and dark themes, first-run (empty config) and populated states, at 1440/820/390px, on two isolated cores (ports 18412/18413, scratch --data-dir and --config). ~90 Playwright screenshots, programmatic WCAG contrast sampling, and real MCP traffic (reads/writes/destructive, failures, a sensitive-data hit, repeated identical calls). Screenshots are not committed — each finding names the state to reproduce.

36 findings, ranked P0–P3, each with view, evidence, heuristic violated, suggested fix and S/M/L effort. Audited against Nielsen + empty/error/loading states + WCAG AA + responsive, plus the house activity-UI rules (grouping, failure-only status, intent reason, histogram/log parity).

Top of the backlog:

  • Activity Log and the Usage tab report different totals for the same 24h window (70 vs 42 calls), and Activity's own filter tiles don't sum (15+4 ≠ 42).
  • The default landing page carries no analytics; Usage.vue has no route, no sidebar entry, no deep link.
  • The first-run Servers empty state has no CTA at all, while Tools and Agent Tokens in the same build have exemplary ones; Secrets can't add a secret at all.
  • Add Server modal's submit sits 594px below the fold, Escape doesn't close it, focus never enters the dialog.
  • The "Docker isolation disabled" security warning is the least legible text on the Dashboard at 1.28:1; every filled primary button is at 4.13:1.
  • The sensitive-data drawer prints the AWS key it just flagged in cleartext.

Docs-only. website build verified locally (npm ci && npm run build, exit 0, 168 documents processed).

Heuristic + live-instance audit of every routed Web UI view in light/dark,
first-run and populated states, at 1440/820/390px. 36 findings ranked P0-P3
with view, evidence, heuristic violated, suggested fix and effort.

Audited against standard heuristics plus the house activity-UI rules
(grouping, failure-only status, intent reason, histogram/log parity).
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 25, 2026 •

Copy link
Copy Markdown

Deploying mcpproxy-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 91d8cf1
Status: ✅  Deploy successful!
Preview URL: https://ae6bb3ee.mcpproxy-docs.pages.dev
Branch Preview URL: https://audit-ux-webui-sweep.mcpproxy-docs.pages.dev

View logs

@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@github-actions

github-actions Bot commented Aug 25, 2026 •

Copy link
Copy Markdown
Contributor

📦 Build Artifacts

Workflow Run: View Run
Branch: audit/ux-webui-sweep

Available Artifacts

  • archive-darwin-amd64 (29 MB)
  • archive-darwin-arm64 (26 MB)
  • archive-linux-amd64 (17 MB)
  • archive-linux-arm64 (15 MB)
  • archive-windows-amd64 (29 MB)
  • archive-windows-arm64 (25 MB)
  • frontend-dist-pr (0 MB)
  • installer-dmg-darwin-amd64 (23 MB)
  • installer-dmg-darwin-arm64 (21 MB)

How to Download

Option 1: GitHub Web UI (easiest)

  1. Go to the workflow run page linked above
  2. Scroll to the bottom "Artifacts" section
  3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 32974796695 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

github-actions Bot pushed a commit that referenced this pull request Aug 25, 2026
* fix(activity): count calls once, so Activity and Usage agree

The Activity Log header and the Dashboard's Usage tab reported different
totals for the same 24-hour window on the same instance. On a repro
instance the same traffic produced three numbers within seconds:

  Activity header       51 calls   (every activity record in the window)
  Usage "Activity over time"  25   (calls the user made)
  Usage "Tool calls" tile     19   (a client-side sum of `tools`)

The two Usage numbers sat on the same screen, one directly above the
other.

Root causes, one per surface:

  * handleActivitySummary counted every record type as the header's
    total, and the frontend labelled that total "N calls". Security
    scans, quarantine auto-approvals and system starts are rows in the
    log, not calls.
  * Usage.vue summed `tools` client-side. That list is
    lifetime-cumulative (the window only filters which tools appear),
    upstream-only (mcpproxy's own retrieve_tools/describe_tool calls
    vanish) and truncated to top-N (the tail is silently dropped).

Both now draw on one definition — storage.CountsAsCall — which the usage
aggregate already applied implicitly and now consults explicitly, so the
timeline, the summary endpoint, the Web UI and the CLI cannot drift
apart. The summary gains call_count/call_error_count; the usage response
gains total_calls/total_errors, computed server-side as the sum of the
timeline it carries. The event total is still reported, under its own
name, because it is the paginator's denominator.

After, on the same instance: Activity reads "83 events · 50 calls · 12
errors" and Usage reads "Calls 50 · Errors 12 · 24.0%".

Audit finding F1 (also F24) — #1046

* docs(storage): correct the call_tool_* exclusion rationale

ActivityFilter.ExcludeCallToolSuccess hides EVERY call_tool_* record, not
only successful ones — a dispatched call emits its own tool_call record
under the same request id whatever the outcome, and a shed one is written
by the limiter. So there is no pre-dispatch failure the counter loses;
the exclusion matches the list's own.

* docs(cli): show events and calls apart in the activity summary sample

* docs(contracts): disclose the usage read-cache skew on the parity contract

Cross-model review flagged that the usage endpoint serves a snapshot
behind observability.usage_cache_ttl (5s) while the summary endpoint
counts live, so a call can reach the Activity Log a few seconds before
the Usage tiles. That is inherent to the endpoint never scanning the log
per request (SC-005), it is bounded, and freshness_ms already discloses
it — so it is documented on the contract and in the parity test rather
than traded away.

* fix(httpapi): judge usage-cache freshness against the live TTL

usage_cache_ttl is hot-reloadable and it is the documented bound on how
far the Usage figures may lag the Activity Log. The cache banked an
absolute expiry from the TTL in force when the entry was written, so
lowering the TTL left entries alive past the new bound — an operator
tightening the bound got no effect until the old expiry passed. Entries
now record when they were stored and freshness is judged against the TTL
in force at read time.

Found by cross-model review of the F1 parity work.

* test(httpapi): age the usage-cache entry instead of trusting the clock

TestUsageCacheHonoursAHotReloadedTTL asserted a 1ns TTL rejects an entry
written moments earlier. On a Windows runner two adjacent time.Now()
calls can report zero elapsed time, so nothing was older than any TTL and
the test failed there. It now back-dates the entry by a minute and checks
a lowered TTL rejects it and a raised one accepts it — no sleeping, no
dependence on clock granularity.
Dumbris added a commit that referenced this pull request Aug 25, 2026
Audit findings F2, F5, F22, F23, F25, F26, F27 and the Activity/Usage
part of F36 (#1046). Builds on #1048's storage.CountsAsCall contract.

F2 — the status tiles are a partition again. ActivitySummaryResponse
gains other_count: the rows whose status is outside the tool-call
vocabulary (a quarantine change stores its action there, a policy
decision its verdict). They were in the total and in no tile, so the
row read 15+4+0+0 under a 42. The tile list now lives in one pure
function, an "Other / internal" tile renders the residual, it filters
like every other tile, and Go + Vitest tests assert the sum.

F5 — repeats fold. Consecutive rows that agree on everything the
collapsed line prints become one expandable run. Status is part of the
run identity, so a run can never mix outcomes and "echo x12" can never
hide the one call that failed; the sensitive-data flag and the
code_execution parent link are in the identity for the same reason.
Folding is on by default, remembered, and off whenever the table is
sorted by something other than time. Successful rows no longer print
"Success" at all — the word stays for screen readers only, so the
marked rows in the column are exactly the ones needing a human.

F22 — the usage charts stop inventing tools and stop quantizing
latency. Names that never completed a call are excluded from "Calls per
tool" and "Token sinks" (named in a footnote, still charted under
errors, and counted the same way by the "active tools" tile).
latencyBucketBoundsMs gains sub-10ms resolution, which is where local
MCP servers live and where the old first bucket had none; Percentile
now reports whether it hit the unbounded overflow bucket, so a figure
renders as a bound ("<= 5 ms") or a floor ("> 10 s") and never as a
stopwatch reading. Every chart axis says what it measures.

F23 — the tokens-saved headline explains itself. It is a structural
estimate over the current tool catalog, so it correctly does not move
per call; the label said otherwise. Relabelled per-request, given the
derivation on hover, and the Dashboard chip now opens the breakdown
that computes it.

F25 — a security_scan drawer shows its verdict and findings by severity
and offers the server and the Security page. A session id is now a
control: filter this log, or open Sessions.

F26 — the Intent column paints the operation word beside the glyph, the
Sensitive badge carries an accessible name, and the filter panel holds
a visible legend for both.

F27 — the Connected tile names its denominator ("2 of 3 enabled
online"): a switched-off server is not an outage. serverCount.disabled
is now asked directly and excludes quarantined servers, so the
Dashboard rail stops reporting one server as two problems.

F36 — the Sessions "View Activity" button stops clipping its label.
github-actions Bot pushed a commit that referenced this pull request Aug 25, 2026
…1052)

* fix(webui): make the Activity and Usage numbers say what they mean

Audit findings F2, F5, F22, F23, F25, F26, F27 and the Activity/Usage
part of F36 (#1046). Builds on #1048's storage.CountsAsCall contract.

F2 — the status tiles are a partition again. ActivitySummaryResponse
gains other_count: the rows whose status is outside the tool-call
vocabulary (a quarantine change stores its action there, a policy
decision its verdict). They were in the total and in no tile, so the
row read 15+4+0+0 under a 42. The tile list now lives in one pure
function, an "Other / internal" tile renders the residual, it filters
like every other tile, and Go + Vitest tests assert the sum.

F5 — repeats fold. Consecutive rows that agree on everything the
collapsed line prints become one expandable run. Status is part of the
run identity, so a run can never mix outcomes and "echo x12" can never
hide the one call that failed; the sensitive-data flag and the
code_execution parent link are in the identity for the same reason.
Folding is on by default, remembered, and off whenever the table is
sorted by something other than time. Successful rows no longer print
"Success" at all — the word stays for screen readers only, so the
marked rows in the column are exactly the ones needing a human.

F22 — the usage charts stop inventing tools and stop quantizing
latency. Names that never completed a call are excluded from "Calls per
tool" and "Token sinks" (named in a footnote, still charted under
errors, and counted the same way by the "active tools" tile).
latencyBucketBoundsMs gains sub-10ms resolution, which is where local
MCP servers live and where the old first bucket had none; Percentile
now reports whether it hit the unbounded overflow bucket, so a figure
renders as a bound ("<= 5 ms") or a floor ("> 10 s") and never as a
stopwatch reading. Every chart axis says what it measures.

F23 — the tokens-saved headline explains itself. It is a structural
estimate over the current tool catalog, so it correctly does not move
per call; the label said otherwise. Relabelled per-request, given the
derivation on hover, and the Dashboard chip now opens the breakdown
that computes it.

F25 — a security_scan drawer shows its verdict and findings by severity
and offers the server and the Security page. A session id is now a
control: filter this log, or open Sessions.

F26 — the Intent column paints the operation word beside the glyph, the
Sensitive badge carries an accessible name, and the filter panel holds
a visible legend for both.

F27 — the Connected tile names its denominator ("2 of 3 enabled
online"): a switched-off server is not an outage. serverCount.disabled
is now asked directly and excludes quarantined servers, so the
Dashboard rail stops reporting one server as two problems.

F36 — the Sessions "View Activity" button stops clipping its label.

* fix(webui): widen the run identity to everything the folded row prints

Cross-model review found three ways a run could fold away something the
collapsed line was displaying on the members' behalf:

- the intent OPERATION TYPE was not in the key, so a run of
  call_tool_write calls against a tool could fold under a "read" lead —
  the two produce records identical in type, server, tool and status.
- only the sensitive-data BOOLEAN was in the key, but the badge prints
  the severity glyph and the detection count, so a critical detection
  could fold under a low-severity lead.
- the key was a space-joined string over free-form fields (server name,
  tool name, details text), so two different rows could agree on one
  joined value. It is JSON.stringify now.

The reason stays out of the key on purpose — that is what reasonsVary
reports. Four regression tests, one per hazard.

* fix(activity): stop dropping the scan findings summary, and clamp the page

Three more from cross-model review.

The settled-scan event carries its rollup as a map[string]int, and
handleSecurityScanSettled read it with a map[string]interface{} type
assertion that never matched — so findings_summary was dropped from
every security_scan record ever written. Nothing noticed because
nothing rendered it; F25's new drawer does. The read now takes the
concrete type (and a JSON round-tripped one), and keeps an EMPTY rollup,
because "the scanners found nothing" and "this record has no summary"
are opposite claims and the drawer must not print the first when it only
knows the second. It now says so, and points at the Security page.

The Activity paginator never clamped currentPage, so folding repeats on
while on a later page — or any refresh that shrinks the list — rendered
an empty table with no hint why. Clamped on the derived page count, so
every path is covered by one rule. Expanded runs and the page now also
reset on a sort, session-filter or grouping change; a run key is a lead
row's id, and a stale one re-expands the wrong run.

The Usage "active tools" figure counts what is charted, so it now admits
the folded tail when the server truncated the list.

* fix(webui): three tie-breaks and one export that would come back empty

Cross-model review, round three.

Exporting from the "Other / internal" view sent that synthetic status to
an endpoint that matches the closed vocabulary exactly, so the file came
back empty — which reads as "there was nothing there". The export drops
the status filter instead; a wider export is recoverable.

Sorting by p95 could not tell a tool BOUNDED at the last histogram
bucket from one that ran PAST it, and the response is truncated to
top-N, so the genuinely slow tool could be dropped in favour of one that
merely touched the ceiling. The overflow flag now breaks that tie.

A failed scan can still carry findings: the debouncer keeps the last
non-nil rollup, so a storm where some scanners finished and a later one
failed settles as "failed" with real findings attached. The drawer shows
them — hiding real findings is the worse error in a security view — and
labels them as partial rather than as the scan's verdict.
The document read as an open P0-P3 backlog, but eight PRs merged on 2026-08-25
(#1044, #1048, #1049, #1050, #1051, #1052, #1053, #1054) closed it. Anyone
opening this file against current main was being handed 36 stale defects.

Added a status banner and a Resolution section that separates four things:

- Re-checked live on v0.61.0 against a running isolated core with real /mcp
  traffic: F1, F4, F5, F6, F7, F8, F12, F13, F20, F24, F26, F33 confirmed fixed,
  each with the observed evidence rather than a PR reference.
- Not re-checked: named explicitly rather than implied, so the next reader knows
  which closures rest on a PR body and which on an observation. F28 is called
  out as partial - its "key called optional" half is fixed, its
  three-surfaces-at-once state is not.
- Corrections to the audit itself: F23 mis-diagnosed a per-request structural
  estimate as a stale aggregation, and F31's "Manual badge has no tooltip" half
  was wrong even at audit time (spec-088 trust-mode badge, already titled).
- Five defects found on main while re-checking, recorded separately since they
  are not regressions of anything in the audit. The first is security-relevant:
  quarantining a server through the config file leaves its tools in the search
  index, so retrieve_tools still hands the agent their names and descriptions -
  which is exactly what quarantine exists to prevent - before the call is
  refused. Runtime.QuarantineServer purges the index; the reload path detects
  the same transition (quarantined_changed: true) and does not.

F6 carries a methodology note. Re-checking it produced a false negative: Escape
driven through the browser-automation layer never reaches the page's document
keydown listener, so the dialog looked stuck open. Dispatched in-page it closes
at once, and #1050's useModalA11y is wired into all five <dialog :open> modals.
The sweep assertion this document proposes must dispatch in-page, or it tests
the automation layer instead of the app.

Also corrects the record on #1053: its body names F1-F16, which is the tray
audit's numbering mis-pasted. #1055 is the tray PR; #1053 touches no Swift file.
@Dumbris
Dumbris force-pushed the audit/ux-webui-sweep branch from a584333 to 91d8cf1 Compare August 26, 2026 13:32
@Dumbris
Dumbris merged commit 99c721a into main Aug 26, 2026
38 checks passed
Dumbris added a commit that referenced this pull request Aug 27, 2026
…Web UI presentation defects (#1065) (#1072)

* fix(quarantine): stop counting a quarantined server's tools as available (#1064)

A quarantined server kept reporting its tools as available. `tool_count` stayed
at its pre-quarantine value, `GET /api/v1/tools` returned every one of them, and
the Servers page rendered the total under "Available across all servers" — while
the search index correctly excluded them (#1061) and every call to those tools
was refused with a SECURITY BLOCK. Two surfaces describing the same catalog
disagreed, and the one an operator reads was the wrong one.

Quarantine is neither "disabled" nor "disconnected": a quarantined server stays
dialed with status ready on purpose, so the tray and Web UI can inspect it for
review. It therefore passed the existing disabled/not-connected guard untouched.
The stale count also survives the supervisor's disconnect-zeroing, because
LoadConfiguredServers re-dials the server and the next reconcile re-sticks the
retained snapshot.

Adds one shared predicate, config.ServerContributesTools(enabled, quarantined),
mirroring the answers runtime.serverEligibleForIndexing already gives the index
writer and preflight.ClassifyTool gives dispatch, and adopts it at the surfaces
that were each re-deriving "available" from a different field:

- Projections zero the per-server count at the wire boundary:
  Runtime.GetAllServers, Server.GetAllServers, and both GetUpstreamStats paths
  (including the manager fallback, whose cached tool count no quarantine path
  invalidates).
- Aggregates gate the sum: management.ListServers, Server.GetUpstreamStats,
  Manager.GetTotalToolCount.
- GET /api/v1/tools and GET /api/v1/annotations/coverage skip quarantined
  servers. Skipping is a deliberate exclusion, not a fetch failure, so neither
  sets `partial`/`failed_servers`.
- getVisibleToolCount returns 0 for a quarantined server.
- The Web UI's totalTools excludes them too.

Deliberately unchanged:

- GET /api/v1/servers/{id}/tools still returns the full list. That is the
  review surface — it is how an operator inspects and approves a quarantined
  server, and after #1061 the StateView is its only source. Same for
  Server.GetQuarantinedServers, which exists to say how many tools await review.
- isToolCallable stays quarantine-blind. It is the *search* filter and must
  reproduce merge-base semantics exactly (Spec 085 FR-006/FR-011), which require
  retrieve_tools to keep surfacing a quarantined server's lingering indexed
  tools; the stricter toolVisibleToSession applies the quarantine gate.
  TestVisibleToolCount_QuarantinedServer pins both halves so the two cannot be
  collapsed again.
- stats.quarantined_servers and health admin_state=quarantined are untouched —
  they are the counterpart that must still show a non-zero number.

Behaviour change worth calling out at review: users with quarantined servers
will now report lower tool counts in /api/v1/status, the SSE servers.changed
embed, /api/v1/profiles, the Prometheus tools-total gauge, the telemetry
heartbeat, and the TOOLS column of `mcpproxy upstream list`.

* fix(webui): three presentation defects — contradictory card, raw enum, stale auth error (#1065)

1. A server card asserted two contradictory security states at once

   The card rendered a green "Clean" scan verdict directly above a yellow
   "Quarantined — needs security review" banner. Both are individually true, but
   stacked as peers they tell the operator opposite things: the scan verdict is
   about CONTENT, quarantine is about REVIEW STATE.

   While quarantined, the standalone verdict badge is suppressed and the verdict
   is folded into the banner as a subordinate clause ("Last scan: clean — still
   needs review"), so the card carries exactly one security headline. This is the
   subordination ServerDetail's spec-088 banner already does, and the same shape
   as the #938 held-tools downgrade one level up. Nothing changes when the server
   is not quarantined. Every verdict still ends in a request to review, including
   the failed case, which is an INCOMPLETE scan and never a threat verdict.

   The Servers v-memo key gains security_scan.status and finding_counts.warning:
   the store updates server objects in place to preserve identity, so without
   them a scan settling on an already-quarantined server left a stale verdict.

2. The Activity Type column mixed two vocabularies

   formatType fell through `|| type` for anything unmapped, so raw snake_case
   landed in a column otherwise full of title-cased prose. Four backend types had
   no label, not the one reported: tool_quarantine_change, security_scan (already
   rendering raw today — it has had a findings drawer since #1046),
   credential_broker and prompt_get.

   The map is completed and exported as ACTIVITY_TYPE_LABELS, and the passthrough
   is replaced with a snake_case -> Title Case fallback so an unmapped value can
   never leak raw again. Server-level and tool-level quarantine keep distinct
   labels. The filter dropdown is derived from the same map instead of being
   hand-copied (it was three types short), and ActivityWidget's duplicate icon map
   is deleted in favour of the shared one.

   The recurrence guard lives in Go, not vitest:
   internal/storage/activity_label_parity_test.go fails when a backend type has
   no Web-UI label. .github/workflows/frontend.yml is path-filtered to frontend/**,
   so a vitest-only guard would never run on the Go-only change that adds a type.
   A second test asserts ValidActivityTypes covers every declared constant, so the
   first cannot go vacuously green.

3. A stale auth error survived a successful sign-in

   With no stored key, /ui/activity showed the auth modal, an inline red
   "Invalid or missing API key" panel behind it, and a Disconnected chip. Entering
   a valid key re-authenticated the header — counts and the Live badge came back —
   but the view body kept the red panel and rendered zero rows until the user
   clicked Retry by hand. Every view holds its load error in a component-local ref
   that nothing outside the component can reach, and no auth-recovered signal
   existed to reach it.

   Adds a monotonic authEpoch to the system store, bumped by markAuthRecovered()
   only on a genuine failed->ok transition. App.vue keys <router-view> on it, so a
   repaired auth remounts the current view and its error, loading state and data
   reset to their declared initial values while onMounted re-runs. Keyed on
   authEpoch alone: folding in the route path would remount ServerDetail on every
   :serverName change and break the Dashboard's single instance across /, /usage
   and /overview.

   reloadAfterAuth() re-primes the surfaces the key cannot reach (fetchInfo,
   fetchRouting, checkAuth — the router guard does not run for a key-driven
   remount), and SidebarNav watches the epoch for its badge counts rather than
   being remounted, which would also reset its open submenu and scroll.

   AuthErrorModal's "Refresh & Retry" now validates the reloaded key before
   reporting success and emits `refresh(verified)`. It previously cleared the
   auth flag without verifying anything, which is why it could not safely
   invalidate views — and why the stale panel survived on that path.
Dumbris added a commit that referenced this pull request Aug 29, 2026
…inish the ux-audit sweep (#1085)

* chore(roadmap): truth-sync ux-audit and upgrade-nudge

Two epics claimed a state the repo contradicts.

upgrade-nudge was `done` with all four tasks done, but Spec 079 FR-002 —
the human-readable "N releases / M weeks behind" delta required on status,
doctor, the startup log, the Web UI and both trays — was never built. The
four shipped tasks are US-slices and the FR belonged to none of them; spec
079 has only spec.md, so no checkbox surface could catch the gap. It
survived only as TODO(spec-079/FR-002) comments in
internal/updatecheck/checker.go and cmd/mcpproxy/status_cmd.go, which is
how an outside contributor found it (#1081). Epic back to in_progress with
an explicit upgrade-nudge-delta task.

ux-audit was `todo` with both sweeps todo, but both shipped in August
(#1046 Web UI, 36 findings; #1043 macOS tray, 16 findings) along with ten
PRs closing every finding and the five defects the re-check pass raised
(#1061/#1064/#1065, all closed). Recorded the sweeps and fix waves as done
and added the two items that really are open: folding the audit's F6 modal
Escape/focus and F1 cross-view total assertions into e2e/web-ui-sweep, and
verifying the tray fixes on a running tray (the 2026-08-26 re-walk found
the installed tray still on v0.60.0, so #1055 remains unobserved).

Also cleared the two --check-github errors, neither introduced here:

- tpa-db and mcp-2026-upgrade each linked a docs(specs) PR in `pr:`. That
  field is implementation evidence, so a spec merge read as "epic done".
  Both entries' own notes already said implementation had not started;
  moved the refs into the notes and left the statuses honest at todo.
- analytics-default-landing (#1044) and schema-deferred (#1063, tasks.md
  89/89) were genuinely finished and are now done.

* feat(079): "N releases / M weeks behind" upgrade delta (FR-002)

Closes the last outstanding slice of Spec 079. FR-002 requires the
current version, the latest version AND a human-readable delta on
`mcpproxy status`, `doctor`, the startup log, the Web UI and both trays;
what shipped was latest-version-only, and the deferral survived as
TODO(spec-079/FR-002) comments that an outside contributor found (#1081).

The blocker was data, not rendering: the checker fetched only
/releases/latest, so it had the offered release's publish date but not the
running one's, and no tag sequence to count.

internal/updatecheck/delta.go computes the delta as a pure, network-free,
clock-free function, so every spec rule is a table row. Fetching is a
best-effort enrichment hung off the existing check — never a second check
pipeline (FR-001):

- one page of /releases (ETag-conditional, so a repeat costs no rate-limit
  budget), plus a by-tag lookup only when the running build predates that
  page and its date is therefore unknown;
- both requests share one context deadline. A per-request timeout bounds
  each hop and nothing bounds the total, and CheckNow runs synchronously
  inside GET /api/v1/info?refresh=true, so an unbounded delta would stall
  a request a user is waiting on;
- counting is by semver, never by list position: GitHub orders the list by
  created_at, and the live data has v0.53.0-rc.9 sitting ahead of the
  later-published rc.10.

Three degradation rules matter more than the feature. A delta miss must not
set CheckError (statusVersionSuffix returns "" whenever it is non-empty, so
that would DELETE the nudge instead of enriching it), must not touch the
FR-018 backoff counters, and must leave every surface rendering exactly what
it rendered before. There is a regression test per rule.

The clause is rendered once in Go (FormatBehindSummary) and printed verbatim
by every surface, with the raw numbers alongside for machine consumers. That
is deliberate: GuidanceLine is already hand-ported into UpdateBanner.vue with
a "keep the two in sync" comment, and FR-002 asks for consistent framing
across five surfaces.

Fields are additive per FR-021 and had to be threaded through six
hand-maintained mirrors — VersionInfo, the InfoResponseUpdate DTO and its
copier, internal/contracts (→ make swagger), the contracts.ts generator,
status_cmd's map decoding, and the Swift tray's Codable, which turned out
never to have decoded the US2 fields either.

Two adjacent bugs fixed because the delta sits on the same code:

- GetLatestReleaseIncludingPrereleases returned releases[0] from a
  created_at-ordered list, so an RC user could be offered a release older
  than one already published. Now max-by-semver.
- GetReleaseByTag interpolated an unvalidated tag into the request path and
  deferred validation to callers by comment only. The delta feeds it the
  ldflags-stamped version, so it now validates and escapes.

Both trays render the delta in the update item's tooltip rather than its
title: Spec 092 FR-010 fixes the title's exact shape, and a menu row reading
"Update v0.62.0 — ready to restart? — 8 releases / ~14 weeks behind" stops
being scannable.

Known bound, accepted deliberately: the scan reads one 100-release page, so a
build older than that window reports a lower bound ("59+ releases") and a
semver-in-range release created long ago can be missed without setting that
flag. Spec 079's own assumption (L159) allows an approximation where an exact
count is unavailable, and the figure is motivational, not load-bearing.

Verified: unit + integration tests against an httptest GitHub (delta,
saturation, tag fallback, 304 reuse, budget, malformed tags), `go test -race`
across internal and cmd, golangci-lint v2 clean, 962 frontend unit tests, and
a live version-stamped instance confirming the degradation path renders the
pre-delta output when the check fails.

* test(ux-audit): finish the sweep's regression net, and fix what it caught

The August Web UI audit closes by asking for four assertions to be folded
into the committed sweep. Three were already there (F9 contrast, F30
accessible names + aria-live, F14 responsive); this adds the two that were
not, and then fixes the defects they immediately exposed on main.

F6 — the Add Server modal takes focus, traps Tab, closes on Escape and
restores focus to its trigger. These `<dialog :open>` modals are opened by
the `open` attribute rather than showModal(), so none of that comes from the
browser; it all comes from useModalA11y, whose own comment delegates the
real-browser half of its coverage to "the Playwright sweep" — a promise the
sweep did not keep. Escape is dispatched IN-PAGE, never via
page.keyboard.press: re-checking F6 during the audit produced a false
negative for exactly that reason, because a synthetic key never reaches the
document listener under test.

F1 — Activity and Usage must report the same 24h numbers as the API. The
invariant is not naive equality: Usage folds `blocked` into its error tile
while Activity splits them, and /activity/usage is served from a short read
cache while /activity/summary counts live, so the assertion polls for
convergence and encodes the real relationship.

Running the completed sweep turned up three defects already on main, none of
them regressions of the audit's 36:

1. The LANDING PAGE failed AA in both themes (3.09-4.23:1) and two of its
   controls had no accessible name. Usage.vue uses the raw `opacity-*`
   utility for muted text; #1054 fixed that failure mode for the
   text-base-content ramp and .stat-* but never covered raw opacity, and
   nothing caught it because the audit walked `/` before #1044 made Usage
   the landing page. Moved onto the AA-checked --tone-muted; both selects
   got an aria-label.

2. The Activity status pill clips at 390px for any status outside the known
   four. An unmapped status falls through to a ghost pill carrying the raw
   value, and `tool_auto_approved` measured 145px inside a 93px cell (the
   table is table-fixed below 640px). The pill now truncates against the
   cell and keeps the full value in its title, rather than the column being
   sized to today's longest label — which would hold only until the next
   status is added.

The phone check that finally caught #2 had been passing vacuously: it
measures rows.first(), and a `success` row — ~90% of traffic — renders an
sr-only label of zero width. It only became a real assertion once the new F1
check generated an error row and put one first. That coupling is worth
knowing about: the sweep shares one instance, so one check's traffic is the
next check's data, and a newly-failing neighbour after adding a check is more
likely a real find than a flake. Both were separated from the change under
test by running the same sweep against clean HEAD.

Sweep: 25 passed / 3 failed on clean HEAD, 30 passed / 0 failed now.

Roadmap: ux-audit was still carrying both sweeps as `todo` although they and
every finding shipped in August; recorded here along with what the completed
net found.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants