feat(cli): remediation hints on scan/test failures

[albatrossflyon-coder]

Summary

Fixes #245.

Note: this branch is built on top of #281 (feat/quiet-flag-wiring) — GitHub won't let me set that as the PR base cross-repo (only exists on my fork), so this diff includes #281's commit too until that one merges and I can rebase. The remediation-hints-specific commit is the second one in the PR — happy to rebase onto main directly right now instead if you'd rather review this standalone.

What I found

The issue's ask was "error messages should include a remediation hint" — but digging in, test doesn't even show the error message today, let alone a hint. Reproduced live:

$ mcp-observatory test nonexistent-command-xyz
  ✗ nonexistent-command-xyz    0 tools, 0 prompts, 0 resources
  (nothing else — no error, no diagnosis, no hint)

Also found this codebase already has a much richer diagnosis system than what the issue's suggested fix implies: formatConnectionFailureDiagnosis (src/utils/failure-diagnosis.ts) produces a full diagnosis/likely-causes/next-steps block, stored in RunArtifact.fatalError — but it's only rendered by renderWatchFirstRun/renderRunTerminal (used by watch and single-target renderers), not by scan or test's own inline printing. scan shows just the diagnosis header line; test shows nothing at all.

Fix

• suggestFix() (helpers.ts) — the lightweight one-line lookup the issue asked for (timeout / ECONNREFUSED / ENOENT-spawn / invalid-JSON), for the failure classes outside the rich diagnosis path (thrown exceptions before a connection is even attempted, config parsing errors)
• firstNextStep() (failure-diagnosis.ts) — pulls the first "Next steps:" bullet out of the existing rich diagnosis, for scan/test's one-line-of-room display
• scan.ts — exception catch block gets suggestFix() after the existing friendly message; the fatalError display (previously header-only) now also shows firstNextStep()
• test.ts — was showing nothing on failure; now shows the fatalError header plus firstNextStep() ?? suggestFix(), matching scan.ts's pattern

Verified live

$ mcp-observatory test nonexistent-command-xyz
  ✗ nonexistent-command-xyz    0 tools, 0 prompts, 0 resources
    → Could not establish a plain stdio MCP session for target `nonexistent-command-xyz`.
    → Run the command manually and look for usage output, auth prompts, or crash text.

Same improvement confirmed on scan against a config pointing at a broken server.

Testing

• New tests: 5 for suggestFix(), 3 for firstNextStep() (extracts first bullet, handles no-Next-steps text, handles Next-steps-with-nothing-after)
• npx tsc --noEmit: clean
• npx eslint on all changed files: clean
• Full suite: same 59 pre-existing failures as main (environment-specific, unrelated — see feat(scan): add passed/failed/warnings summary line #280/fix(cli): wire up --quiet to actually suppress logo and CTAs #281 for the same confirmation)

[KryptosAI]

@albatrossflyon-coder great work on these! #281 and #284 are merged. #283 conflicts with #281 since both modify the same files. Could you rebase #283 on top of the current main? The --quiet changes from #281 are already in — your remediation hints PR just needs to rebase cleanly on top. Thanks for the incredible pace!

[KryptosAI]

@albatrossflyon-coder hey — #281 is merged now. There are minor conflicts in and that need resolving. Happy to fix them for you and merge, or you can rebase whenever you have time. Your call — great work as always.

[albatrossflyon-coder]

Coverage gap in src/tools/ — filed as #282

Hey William,

Following up after digging into a few issues on mcp-observatory (just shipped #280 and #281) — found something worth flagging separately: your coverage CI check has been failing on main for a few days now, not tied to any specific PR. Root cause is src/tools/* sitting at 10-15% coverage against a 90% global threshold. Filed the details as #282, didn't attempt a fix since it's real scope, not a quick pass.

Appreciate the follow — been enjoying working in this codebase.

[albatrossflyon-coder]

Rebased onto current main — conflicts with #281 are resolved, PR shows mergeable now. Thanks for the flag!

[KryptosAI]

Merged — this is excellent work. The test.ts fix alone is worth the PR (showing nothing for failures was a real papercut). Clean integration of the existing rich diagnosis system into the inline output, solid test coverage, and thanks for catching the setup-ci-conversion prompt format drift too. Really appreciate the thoroughness and the rebase turnaround!