Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
231 changes: 126 additions & 105 deletions ROADMAP.md

Large diffs are not rendered by default.

11 changes: 11 additions & 0 deletions cmd/generate-types/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -555,6 +555,17 @@ export interface UpdateInfo {
// Spec 079 US3 (FR-019): the core runs in a CI / non-interactive context —
// UI surfaces must stay quiet while the facts remain machine-readable.
nudges_suppressed?: boolean;
// Spec 079 FR-002 (additive per FR-021): how far behind the running build
// is. behind_summary is rendered by the daemon
// (updatecheck.FormatBehindSummary) and printed verbatim by every surface,
// so the CLI, this banner and the tray cannot word it differently — do not
// re-derive it from the numbers below. All four are absent when the delta
// could not be resolved, or against a daemon too old to send them; the
// banner then renders exactly what it rendered before.
behind_summary?: string;
releases_behind?: number;
releases_behind_saturated?: boolean;
weeks_behind?: number;
}

export interface InfoResponse {
Expand Down
9 changes: 8 additions & 1 deletion cmd/mcpproxy/doctor_cmd.go
Original file line number Diff line number Diff line change
Expand Up @@ -311,7 +311,14 @@ func outputDiagnostics(diag map[string]interface{}, info map[string]interface{},
releaseURL := getStringField(updateInfo, "release_url")

if updateAvailable && latestVersion != "" {
fmt.Printf("Version: %s (update available: %s)\n", version, latestVersion)
// Spec 079 FR-002: the same daemon-rendered delta
// clause status prints, so the two surfaces cannot
// word it differently. Absent from an older daemon.
behind := ""
if b := getStringField(updateInfo, "behind_summary"); b != "" {
behind = ", " + b
}
fmt.Printf("Version: %s (update available: %s%s)\n", version, latestVersion, behind)
if releaseURL != "" {
fmt.Printf("Download: %s\n", releaseURL)
}
Expand Down
45 changes: 39 additions & 6 deletions cmd/mcpproxy/status_cmd.go
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,17 @@ type StatusUpdateInfo struct {
CheckError string `json:"check_error,omitempty"`
InstallChannel string `json:"install_channel,omitempty"` // Spec 079 FR-008
UpdateCommand string `json:"update_command,omitempty"` // Spec 079 FR-009

// BehindSummary is the daemon-rendered "N releases / M weeks behind"
// clause (Spec 079 FR-002). Empty against a daemon too old to send it, or
// when the delta could not be resolved — status then prints the same line
// it printed before the delta existed.
BehindSummary string `json:"behind_summary,omitempty"`
// The raw figures behind that clause, for `status -o json` consumers that
// would otherwise have to parse prose.
ReleasesBehind *int `json:"releases_behind,omitempty"`
ReleasesBehindSaturated bool `json:"releases_behind_saturated,omitempty"`
WeeksBehind *int `json:"weeks_behind,omitempty"`
}

// ServerEditionStatusInfo holds server-edition-specific status information.
Expand Down Expand Up @@ -340,22 +351,44 @@ func extractStatusUpdate(infoData map[string]interface{}) *StatusUpdateInfo {
if v, ok := updateData["update_command"].(string); ok {
u.UpdateCommand = v
}
// Spec 079 FR-002. Absent from an older daemon, which is exactly the
// daemon most likely to be running here — treat absence as "no delta",
// never as an error.
if v, ok := updateData["behind_summary"].(string); ok {
u.BehindSummary = v
}
if v, ok := updateData["releases_behind"].(float64); ok {
n := int(v)
u.ReleasesBehind = &n
}
if v, ok := updateData["releases_behind_saturated"].(bool); ok {
u.ReleasesBehindSaturated = v
}
if v, ok := updateData["weeks_behind"].(float64); ok {
n := int(v)
u.WeeksBehind = &n
}
return u
}

// statusVersionSuffix renders the update annotation appended to the Version
// line, mirroring doctor's presentation. A failed or not-yet-completed check
// renders nothing (quiet on failure; the error stays in JSON for diagnostics).
//
// TODO(spec-079/FR-002): extend the annotation with the human-readable
// "N releases / M weeks behind" delta once internal/updatecheck computes it
// (requires the release list + publish dates, not just the latest release;
// additive per FR-021). This function is the single rendering point.
// Spec 079 FR-002/FR-003: the "N releases / M weeks behind" delta is appended
// here when the daemon reports one. The clause itself is authored by the
// daemon (updatecheck.FormatBehindSummary) rather than assembled here, so
// status, doctor, the startup log, the Web UI banner and the tray cannot word
// it differently. An older daemon omits it and this renders the legacy form.
func statusVersionSuffix(u *StatusUpdateInfo) string {
if u == nil || u.CheckError != "" {
return ""
}
if u.Available && u.LatestVersion != "" {
behind := ""
if u.BehindSummary != "" {
behind = ", " + u.BehindSummary
}
// Spec 079 US2 (FR-009): append the channel's exact one-line update
// command, or the channel-appropriate guidance when no command is
// safe. Older daemons omit install_channel — render the legacy form.
Expand All @@ -371,9 +404,9 @@ func statusVersionSuffix(u *StatusUpdateInfo) string {
}
}
if u.ReleaseURL != "" {
return fmt.Sprintf(" (update available: %s — %s%s)", u.LatestVersion, u.ReleaseURL, action)
return fmt.Sprintf(" (update available: %s%s — %s%s)", u.LatestVersion, behind, u.ReleaseURL, action)
}
return fmt.Sprintf(" (update available: %s%s)", u.LatestVersion, action)
return fmt.Sprintf(" (update available: %s%s%s)", u.LatestVersion, behind, action)
}
if u.LatestVersion != "" {
// A successful check confirmed we are current.
Expand Down
13 changes: 12 additions & 1 deletion docs/api/rest-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -1075,7 +1075,10 @@ Get application info, version, and update availability.
"checked_at": "2025-01-15T10:30:00Z",
"is_prerelease": false,
"install_channel": "homebrew",
"update_command": "brew upgrade mcpproxy"
"update_command": "brew upgrade mcpproxy",
"behind_summary": "8 releases / ~14 weeks behind",
"releases_behind": 8,
"weeks_behind": 14
}
}
}
Expand Down Expand Up @@ -1105,6 +1108,14 @@ Get application info, version, and update availability.
| `update.check_error` | string | Error message if update check failed |
| `update.install_channel` | string | Detected install channel: `homebrew`, `dmg`, `deb`, `rpm`, `docker`, `go-install`, `windows-installer`, `tarball`, or `unknown`. Always present once detected, even when no update is available. See [Version Updates](/features/version-updates) for how detection works. |
| `update.update_command` | string | Exact one-line update command for the detected channel. Only present when an update is available **and** the channel has a safe command (`homebrew`, `deb`, `rpm`, `go-install`); omitted for `dmg`/`windows-installer`/`tarball`/`docker`/`unknown` so a possibly-wrong command is never suggested. |
| `update.behind_summary` | string | Human-readable delta clause, e.g. `8 releases / ~14 weeks behind` (Spec 079 FR-002). **Render this verbatim** rather than rebuilding it from the numbers below — it is authored once in the core so the CLI, Web UI banner and both trays cannot word it differently. Only present when an update is available and the delta could be resolved. |
| `update.releases_behind` | integer | Releases on the offered channel between the running version and the offered one. Absent when unknown. |
| `update.releases_behind_saturated` | boolean | `releases_behind` is a **lower bound**: the running build predates the scanned release window, so older releases were never counted. Clients render `N+`. Omitted when false. |
| `update.weeks_behind` | integer | Whole weeks between the two releases' publish dates. `0` is a real value (a same-week release); *absent* means unknown, so do not conflate them. |

:::note Delta fields degrade silently
The four `behind_*` / `*_behind` fields are best-effort enrichment: resolving them needs the release list and publish dates, which is a second GitHub request. When that request fails, is rate-limited, or the running build has no release record, the fields are simply **absent** and every surface renders exactly the message it rendered before the delta existed. A missing delta never sets `check_error` and never suppresses the nudge.
:::

:::tip Update Checking
MCPProxy automatically checks for updates every 4 hours. The update information is exposed via this endpoint and used by the tray application and web UI to show update notifications. Use `?refresh=true` to force an immediate re-check. Checking is controlled by the `update_check` config block (`enabled`, `channel`) — see [Version Updates](/features/version-updates); when disabled, `?refresh=true` performs no check and the `update` object is omitted.
Expand Down
3 changes: 2 additions & 1 deletion docs/cli/status-command.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,8 @@ mcpproxy status -o json

When the daemon is running, `status` surfaces the result of the background update check (the same `update` object as `GET /api/v1/info` and `mcpproxy doctor`):

- **Update available**: `Version: v1.2.0 (update available: v1.3.0 — <release URL>)`
- **Update available**: `Version: v1.2.0 (update available: v1.3.0, 8 releases / ~14 weeks behind — <release URL>)`
- The `N releases / M weeks behind` clause (Spec 079 FR-002) appears only when the daemon resolved a delta. Resolving it needs a second GitHub request for the release list and publish dates, so it is absent when that request fails or is rate-limited, when the running build has no release record, and against a daemon older than the feature — the line then reads exactly as it did before, without the clause. A build too old for the scanned window reports a lower bound (`59+ releases`).
- **Up to date**: `Version: v1.3.0 (latest)`
- **Check failed or not yet completed** (offline, rate-limited): the version is shown without any annotation. In JSON output the `update.check_error` field retains the failure reason for diagnostics.
- **Update checking disabled** (`update_check.enabled: false` in the config, or `MCPPROXY_DISABLE_AUTO_UPDATE=true`): the daemon performs no check and omits the `update` object entirely, so the version is shown without any annotation.
Expand Down
5 changes: 4 additions & 1 deletion docs/features/version-updates.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ $ mcpproxy doctor
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 MCPProxy Health Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Version: v1.2.3 (update available: v1.3.0)
Version: v1.2.3 (update available: v1.3.0, 8 releases / ~14 weeks behind)
Download: https://github.com/smart-mcp-proxy/mcpproxy-go/releases/tag/v1.3.0

✅ All systems operational! No issues detected.
Expand Down Expand Up @@ -176,6 +176,9 @@ Response includes an `update` field when version information is available:
"update": {
"available": true,
"latest_version": "v1.3.0",
"behind_summary": "8 releases / ~14 weeks behind",
"releases_behind": 8,
"weeks_behind": 14,
"release_url": "https://github.com/smart-mcp-proxy/mcpproxy-go/releases/tag/v1.3.0",
"checked_at": "2025-01-15T10:30:00Z",
"is_prerelease": false,
Expand Down
32 changes: 32 additions & 0 deletions docs/qa/ux-audit-webui-2026-08.md
Original file line number Diff line number Diff line change
Expand Up @@ -615,6 +615,38 @@ These are on `main` today and are **not** regressions of anything listed above:

---

### Found by committing the audit's own regression assertions (2026-08-29)

The closing recommendation below — fold the F6 modal and F1 cross-view checks into
`e2e/web-ui-sweep/` — was carried out. Running the completed sweep immediately turned up three
defects **already on main**, none of them regressions of the 36 above, and each one a case the
sweep could not previously see:

1. **The landing page failed AA in both themes, and two of its controls had no accessible name.**
`Usage.vue` uses the raw `opacity-*` utility for muted text (3.09–4.23:1 measured), and its
status/sort `<select>`s carry their purpose only in their option text. #1054 fixed exactly this
failure mode for the `text-base-content/NN` ramp and `.stat-*`, but never covered the raw
opacity utility — and nothing caught it because the audit walked `/` *before* [#1044](https://github.com/smart-mcp-proxy/mcpproxy-go/pull/1044) made
Usage the landing page. The committed contrast and accessible-name checks walk `/`, so they
found it the first time they ran. Fixed by moving those four sites onto the AA-checked
`--tone-muted` and giving both selects an `aria-label`.

2. **The Activity status pill clips at 390px whenever the status is not one of the four known
ones.** An unmapped status falls through to a ghost pill carrying the RAW value; `tool_auto_approved`
measured 145px inside a 93px cell (the table is `table-fixed` below 640px). The existing F14
phone check never caught it because it measures `rows.first()`, and a `success` row — ~90% of
traffic — renders an `sr-only` label of zero width, so the assertion was vacuous for the common
case. It only became real once the new F1 check generated an error/quarantine row and put one
first. Fixed by letting the pill truncate against the cell rather than sizing the column to
today's longest label, which would only hold until the next status is added.

**Method note worth keeping:** both were found because a new assertion changed what an *existing*
assertion saw. The sweep shares one instance across its tests, so traffic generated by one check is
data for the next — that coupling is what made the vacuous phone assertion finally bite. Treat a
newly-failing neighbouring test after adding a check as a probable real find, not a flake, and
confirm by running the same sweep against clean `HEAD` (which is how these two were separated from
the change under test).

## Reproducing this audit

```bash
Expand Down
68 changes: 68 additions & 0 deletions e2e/web-ui-sweep/visual-a11y-sweep.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -522,3 +522,71 @@ test('header search button is enabled with an empty box', async ({ page }) => {
await page.waitForTimeout(250)
expect(page.url()).not.toContain('/search')
})

// ---------------------------------------------------------------------------
// F6 — the Add Server modal must take focus, trap Tab, close on Escape and
// hand focus back to its trigger.
//
// These five `<dialog :open>` modals are opened by the `open` ATTRIBUTE rather
// than showModal(), so the browser supplies none of the modal affordances;
// every one of them comes from `useModalA11y`. Its own comment delegates the
// real-browser half of its coverage to "the Playwright sweep" — this is that
// test. Without it, deleting the document keydown listener or the nextTick
// focusInitial() passes the whole sweep.
//
// Escape is dispatched IN-PAGE, never with page.keyboard.press(). Re-checking
// F6 during the audit produced a FALSE NEGATIVE for exactly that reason: a key
// sent through the automation layer never reached the document listener under
// test, so the assertion measured the harness instead of the app.
//
// Assert on the `[open]` ATTRIBUTE, not on DOM presence — the modal box is not
// behind a v-if, so it stays in the DOM when closed. Checking "is it in the
// DOM" is how the original audit mis-measured this.
// ---------------------------------------------------------------------------
test('the Add Server modal takes focus, traps Tab and closes on Escape', async ({ page }) => {
// /activity mounts exactly one AddServerModal (TopHeader's). `/` and
// /servers mount a second copy of the same component, which makes the
// data-test locator strict-mode ambiguous there.
await goto(page, '/activity')

await page.locator('[data-test="header-add-server"]').click()
await expect(page.locator('dialog[data-test="add-server-modal"][open]')).toHaveCount(1)

const focus = await page.evaluate(() => {
const box = document.querySelector('[data-test="add-server-modal-box"]')
const active = document.activeElement as HTMLElement | null
return {
inside: !!box && !!active && box.contains(active),
onCloseButton: !!active && active.hasAttribute('data-modal-close-button'),
}
})
expect(focus.inside, 'focus never entered the Add Server dialog').toBe(true)
expect(focus.onCloseButton, 'focus landed on the header ✕ instead of the form').toBe(false)

// Tab from the last focusable wraps to the first instead of walking out into
// the page behind the modal.
const wrapped = await page.evaluate(() => {
const box = document.querySelector('[data-test="add-server-modal-box"]')
if (!box) return null
const focusables = Array.from(
box.querySelectorAll<HTMLElement>(
'a[href],button:not([disabled]),input:not([disabled]):not([type="hidden"]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])',
),
).filter((el) => el.checkVisibility({ checkVisibilityCSS: true }))
if (focusables.length < 2) return null
focusables[focusables.length - 1].focus()
document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', bubbles: true }))
return document.activeElement === focusables[0]
})
expect(wrapped, 'Tab escaped the dialog instead of wrapping to the first control').toBe(true)

await page.evaluate(() =>
document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true })),
)
await expect(page.locator('dialog[data-test="add-server-modal"][open]')).toHaveCount(0)

// Focus restoration is deferred a tick, so poll rather than read once.
await expect
.poll(() => page.evaluate(() => document.activeElement?.getAttribute('data-test') ?? null))
.toBe('header-add-server')
})
Loading
Loading