feat(mcp): suggest the closest command on an unknown command

[glorydavid03023]

Summary

When a command is mistyped, the CLI now offers a "did you mean" hint — the ergonomic that git, npm, and cargo all have:

$ gittensory-mcp staus
Error: Unknown command: staus. Did you mean `status`? Run `gittensory-mcp --help` to list commands.

The suggestion is the nearest known top-level command by Levenshtein distance, within a small edit-distance budget that scales with input length (max(2, floor(len/3))), so unrelated input gets no misleading suggestion and the base Run --help guidance is unchanged.

Behavior / compatibility

• Additive: the existing Unknown command: … Run --help message is preserved; the Did you mean …? clause is only inserted when a close match exists.
• Unrelated input (e.g. bogus-command) gets only the --help guidance, exactly as before.

Scope

• packages/gittensory-mcp/bin/gittensory-mcp.js — suggestCommand() + a small levenshteinDistance() helper (driven by the existing CLI_COMMAND_SPEC), wired into the unknown-command throw.
• test/unit/mcp-cli-basics.test.ts — near-miss typos resolving to status/version/config/doctor, plus the unchanged unrelated-input case.

Packages-only; no src/**, UI, schema, migration, or OpenAPI changes. No README change — this refines an error message, not a command surface.

Validation

Run locally on Node v24.18.0 (engine floor is 22):

• npm run build:mcp → pass
• npm run typecheck → pass, 0 errors (full project)
• npx vitest run test/unit/mcp-cli-basics.test.ts → 20/20 pass, including the new suggests the closest command for a near-miss typo and the unchanged guides unknown commands to --help
• npm pack --workspace @jsonbored/gittensory-mcp --dry-run → package file list unchanged (allowed set; no new files, no secrets)
• Smoke: staus→status, verison→version, confi→config, doctr→doctor; bogus-command → no suggestion

Note: npm run test:mcp-pack can't run on my Windows box (its harness spawnSync("npm", …) can't resolve npm.cmd without a shell) — verified package contents with npm pack --dry-run instead. It passes on CI.

Safety

No auth, cookie, CORS, GitHub App output, identity, contributor-evidence, or scoring changes. No secrets/wallets/hotkeys/trust/reward terms. The suggestion is drawn only from the static known-command list.

Why no issue

This is an intentional no-issue PR: a small, self-contained CLI error-message refinement (a "did you mean" hint on an unknown command) with no public-behavior, auth, schema, deploy, or API-contract change. Per CONTRIBUTING this class of change does not require a tracking issue; happy to file one if maintainers prefer.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-06-30 19:06:47 UTC}

2 files · 1 AI reviewer · no blockers · readiness 73/100 · CI green · unknown

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
The change cleanly wires a top-level command suggestion into the existing unknown-command error path and keeps the base help guidance intact. The Levenshtein helper is local, deterministic, and bounded by the current command spec, so the visible implementation is safe for this CLI surface. The notable gap is test coverage for the no-suggestion branch the PR description calls out.

Nits — 3 non-blocking

• nit: test/unit/mcp-cli-basics.test.ts:161 only checks that unrelated input mentions `--help`, so it would not catch an accidental `Did you mean` hint on `bogus-command`.
• In test/unit/mcp-cli-basics.test.ts:161, capture the thrown error for `bogus-command` and assert the message does not contain `Did you mean` so the distance-budget behavior is locked down.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ No-issue rationale	PR body explains why no issue is linked.
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (no linked issue context).
Validation posture	❌ 5/25	Preflight is holding this PR; address the blocker before review.
Contributor workload	✅ 10/10	Author activity: 194 registered-repo PR(s), 128 merged, 3 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	glorydavid03023; Gittensor profile; 194 PR(s), 3 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: glorydavid03023
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 194 PR(s), 3 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Fix the blocker.
• Triage stale or unlinked PRs.
• Refresh registry data or choose a registered active repo.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review