fix(server): type no-tab rejections so they stop reading as version mismatches

[chrischall]

Closes #204.

Correction to the issue

The issue blamed error-kind.ts:88 and a missing key in the CLI's hint table. That was the wrong classifier. classifyFetchError (error-kind.ts) is what MCP consumers use on fetch results; the CLI uses classifyBridgeError, which dispatches on error type:

if (err instanceof FetchproxyProtocolError) return 'protocol';

So a no-tab rejection was never going to be anything but protocol, and adding a no_tab key to the hint table would have done nothing. The symptom and the remedy were right; the mechanism was not.

The fix

FetchproxyNoTabError, built by protocolErrorFrom like every other typed rejection, carrying the remedy on .hint. Same shape as FetchproxyScopeError, which exists for exactly this reason.

Before

bridge error (protocol): no tab matching https://api.creditkarma.com/
  — extension/server version mismatch — update both.

After (verified live against the original reproduction)

bridge error (protocol): no tab matching https://api.creditkarma.com/
  — open a tab on that host and sign in, then re-run. This is not a
    version problem and does not need an update.

Two decisions worth reviewing

FetchproxyHintedError as a shared base. The CLI now branches on that rather than FetchproxyScopeError. Keying on the concrete subclass is how this bug happened — a hinted error that wasn't a scope error fell through to the blanket advice. With the base, the next hinted error renders correctly with no new branch. FetchproxyScopeError keeps its own identity and ancestry, so existing instanceof catches are unaffected either way.

The content-script variant is deliberately excluded. no tab matching <url> has the fetchproxy content script loaded (N URL matches, none responded) means a tab did match — the remedy is to refresh the page, not open one, and the extension's own message already says so. The regex uses a negative lookahead rather than a bare prefix match, and there's a test pinning that.

Tests

1142 pass across the monorepo (up from 1140). New packages/server/tests/no-tab-error.test.ts covers the typing, the hint content, the raw-error preservation, back-compat with FetchproxyProtocolError/classifyBridgeError, the excluded content-script wording, and non-collision with scope errors — plus a shared-contract block asserting both hinted subclasses render identically. Two CLI tests cover the rendered output.

Note

Anyone on the published CLI (1.4.0) still sees the old hint until the CLI ships too — the branch on FetchproxyHintedError lives in packages/cli. That's how I first "verified" this and got the old string back: the linked local server was producing the new error, but the npm CLI didn't recognise it.

🤖 Generated with Claude Code

https://claude.ai/code/session_012o2nXwu7tov6j7ciBEpigo

[claude]

Claude finished @chrischall's task in 2m 8s —— View job

---

Reviewing PR #205

• Read CLAUDE.md for conventions
• Read PR diff (git diff origin/main...HEAD)
• Review packages/server/src/index.ts and ws-server.ts changes
• Review packages/cli/src/bridge-errors.ts changes
• Review new/updated tests
• Post findings and verdict

Review

The fix introduces FetchproxyHintedError as a shared base for FetchproxyScopeError and the new FetchproxyNoTabError, and switches the CLI's branch (packages/cli/src/bridge-errors.ts:46) from the concrete FetchproxyScopeError to the shared base — exactly the class of bug the PR describes (a hinted error falling through to blanket "protocol" advice because a consumer keyed on one concrete subclass).

Verified in detail:

• Regex correctness (packages/server/src/ws-server.ts:598): NO_TAB_REJECTION = /no tab matching (?!.*content script loaded)/. Checked against the actual extension wording in packages/extension-core/src/background.ts:1569-1575 — the plain rejection (no tab matching <url>) has no content script loaded substring so the negative lookahead succeeds and it matches; the content-script-unreachable variant (no tab matching <url> has the fetchproxy content script loaded (...)) does contain that substring later in the string, so the lookahead fails and the message correctly falls through to plain FetchproxyProtocolError. This matches the PR's stated intent and the new test at packages/server/tests/no-tab-error.test.ts:51-62.
• Backward compatibility: FetchproxyScopeError extends FetchproxyHintedError extends FetchproxyProtocolError, so classifyBridgeError (packages/server/src/classify-bridge-error.ts:42-47, unchanged) still buckets both as 'protocol', and any existing instanceof FetchproxyProtocolError/FetchproxyScopeError catch sites remain correct — confirmed by the shared-contract test block (no-tab-error.test.ts:83-99) and scope-error.test.ts still passing conceptually (class identity unchanged, just re-parented).
• No other in-repo consumers key on FetchproxyScopeError directly — grep'd the whole repo; only packages/cli/src/bridge-errors.ts and the server's own tests reference it, so there's no second call site silently left un-migrated.
• packages/cli/src/verbs/health.ts:69's pre-existing /^no tab matching /.test(err.message) regex still matches, since FetchproxyNoTabError.message is ${originalError} — ${hint} and still starts with no tab matching — no regression there.
• Version-annotation comment style (1.12.0+) matches the existing convention used throughout ws-server.ts for prior additions (0.8.0+, 1.10.0+, 1.4.0+, etc.).
• Note: I was unable to execute the test suite in this sandbox (npm test / npx vitest required approval that wasn't available), so I did not independently verify the 1142-pass count claimed in the PR description — this is an open question, not a finding, per review scope rules. The test file itself (no-tab-error.test.ts) reads as a solid, well-targeted set of assertions covering the typing, hint content, raw-error preservation, backward-compat classification, and the excluded content-script wording.

No correctness, convention, or test-coverage issues found.

No issues found.

Verdict: pass

Branch: fix/no-tab-error-hint

[github-actions]

✅ Auto-review verdict: pass — The fix correctly types no-tab rejections via a new FetchproxyNoTabError sharing a FetchproxyHintedError base with FetchproxyScopeError; regex, class hierarchy, and CLI branch were all verified against source and no regressions or convention violations were found.