Fix: Typo tolerance and clean attach configurations

[abhijeetnardele24-hash]

Closes #466 (Replacing #475 with a clean, unstacked branch). Adds didYouMean for typo suggestions, truly drops unrecognized keys from attach payloads (using supportedAttachKeys), updates Python/JS adapters with known schemas, and cleans up session state for dropped keys.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[debugmcpdev]

Thanks for this — and for the clean unstacked v2 branch, that made it a straightforward review. The core of this PR is exactly what #466 asked for and I want to land it: the supportedAttachKeys inversion is the right idea (a deny-list can only catch mistakes someone predicted; an allow-list catches typos for free), the didYouMean util is tidy, dependency-free, and tested, and riding the existing warning plumbing instead of inventing new machinery is the right call.

One semantic change is needed before merge, plus a few smaller items.

1. Forward unlisted keys — don't delete them (blocking)

Right now an unlisted key is stripped from the transformed config. The problem: the allow-lists are inevitably a subset of what the debuggers actually accept. debugpy also takes logToFile, steppingResumesAllThreads, rules, connect/listen…; js-debug also takes continueOnAttach, sourceMapPathOverrides, restart, trace, outputCapture… None of those are on the lists, so a working advanced config would silently lose keys after this merge.

Pass-through of unknown keys is a deliberate design here (#450, and the docstring on transformAttachConfig this PR rewrites): new upstream debugger capabilities must be usable without an mcp-debugger release. #466 anticipated this exact tension and named the resolution — "keep pass-through, just say so."

So: keep everything you built, but change the semantics for unlisted keys from drop to forward + warn. The warning then needs two truthful buckets:

• keys the adapter's transform actually dropped → were ignored (today's wording stays honest);
• unlisted-but-forwarded keys → something like not recognized by mcp-debugger — forwarded to the adapter as-is: pathMapping (did you mean pathMappings?).

Your instinct that "ignored" must not lie was right — this fixes it in the other direction, without breaking anyone.

2. Warn on the union (blocking)

With supportedAttachKeys present, the new branch replaces the old transform-diff check instead of adding to it — so a listed key that the transform nonetheless drops no longer warns, which quietly loses #450's coverage. The dropped set should be the union: (keys not in the allow-list) ∪ (keys missing from the transform output).

3. Doc comment accuracy

The new supportedAttachKeys doc in packages/shared/src/interfaces/debug-adapter.ts says unlisted keys are stripped "from the payload passed to transformAttachConfig", but the implementation acts on the transform's output. With the forward semantics from (1) the sentence goes away entirely — just make sure the final wording matches what the code does.

4. Tighten the did-you-mean threshold

Distance ≤3 is where misleading suggestions live: real typos are almost always 1–2 edits, while 3 edits reaches different keys — e.g. host on a JS attach (valid concept; js-debug's key is address) would get "did you mean port?". Suggest ≤2 for normal keys (keeping your stricter 1 for short keys). With forward semantics a wrong suggestion is advisory noise rather than a broken config, but tighter is still better — agents tend to obey suggestions.

5. A behavioral test through the attach path

The didYouMean unit tests are good. The only attach-path test touched is server-redefine-and-attach.test.ts, where the warning string lives in a mock — so the new logic in session-manager-operations.ts isn't actually exercised (codecov flags the same 7 lines). Please add a test that drives an attach with a fake adapter declaring supportedAttachKeys and asserts (a) the warning text with the suggestion and (b) that an unlisted key still reaches the DAP attach config.

Nit

server-redefine-and-attach.test.ts lost its BOM byte in the first line — please restore it to keep the diff free of unrelated churn.

---

Happy to re-review quickly once these are in — the shape of the final feature is already here, it's really just the drop→forward flip plus a test.

[debugmcpdev]

Thanks again for this contribution — the supportedAttachKeys + didYouMean design was the right shape, and we wanted to get it shipped, so I've pushed the review items onto your branch directly rather than wait (hope that's okay — your commit and authorship stay intact, and the merge will credit you).

What the follow-up commit (5ed0a49) changes relative to the review:

1. Drop → forward + warn (review item 1): unlisted keys are never deleted from the transformed config. The warning now has two truthful buckets — keys the adapter's transform actually dropped (were ignored) and unlisted-but-forwarded keys (not recognized by mcp-debugger — forwarded to the adapter as-is), both with your did-you-mean suggestions.
2. Union semantics (item 2): a listed key the transform drops still warns as ignored, so python attach has no path-mapping lever — localRoot/remoteRoot/pathMappings silently dropped #450's coverage is intact.
3. Doc accuracy (item 3) and the threshold tightened to 2, strict 1 for keys ≤ 4 chars (item 4) so host can never suggest port.
4. Behavioral tests through the real attach path (item 5) in session-manager-attach-modes.test.ts, plus the BOM restore (item 6).
5. Went one step further for uniformity: all six attach-capable adapters (python, javascript, ruby, java, dotnet, cpp) now declare grounded supportedAttachKeys and use the deny-list pass-through transform pattern — including threading forwarded extras through js-debug's parent and child attach requests, so options like localRoot/sourceMaps genuinely take effect where source resolution happens.

Verified live: a python attach with pathMapping now returns did you mean pathMappings? while still forwarding the key, and a clean attach returns no warning. Merging once CI is green.

[debugmcpdev]

All review items addressed in 5ed0a49 (drop→forward flip with two-bucket warnings, union semantics, doc accuracy, threshold ≤2, behavioral attach-path tests, BOM) — plus the uniform supportedAttachKeys/pass-through rollout across all attach-capable adapters. CI green including codecov/patch. Approving to land.