[pyjeebz]

Closes #8.

Errors from the CLI framework leaked through in its own voice (ports free → accepts 1 arg(s), received 0), and typos got no help. Now every message is in ports' voice, says what's needed with an example to copy, and suggests the nearest real command or name when there's a clear one. Exit codes and stdout are unchanged everywhere. Suggestions go to stderr only, and --json still prints [] on a miss.

Real binary, main vs this branch:

Command	main	this branch	exit
ports free	accepts 1 arg(s), received 0	`ports free` needs a port — e.g. `ports free 3000`	2
ports free 3000 8000	accepts 1 arg(s), received 2	`ports free` takes one port — got 2: 3000 8000	2
ports completion	accepts 1 arg(s), received 0	`ports completion` needs a shell — e.g. `ports completion zsh`	2
ports completion badshell	invalid argument "badshell" for "ports completion"	unknown shell "badshell" — bash, zsh, fish, or powershell	2
ports frees	unknown command "frees" — run `ports --help`	… — did you mean `ports free`?	2
ports dctor	(no hint)	did you mean `ports doctor`?	2
ports find pyhton	nothing matching "pyhton"	… — did you mean "python3.13"?	1
ports kill shp	… — try `ports find shp`	… — did you mean "shop"?	1

How suggestions work:

• Matching uses edit distance where a swapped pair of letters counts as one typo. It also compares against the start of longer names, so pyhton finds python3.13.
• The allowance scales with length: a third of a name query, half of a command query, at most two. So l, h, find x and find ab suggest nothing; they're a few edits from almost anything.
• A whole name beats the start of a longer one: shp means shop, not shop-db.
• A tie suggests nothing rather than guess.
• kill only suggests names it can actually match. A docker row's docker-proxy is never offered; its container and Compose service names are.
• Cobra's own command suggestions only caught prefixes (kil but not frees, wiat or dctor), so commands use the same edit distance.

How it was verified

Gate, locally with CI's versions: unit ✓, build ✓, integration ✓ (uncached), installers ✓, gofmt ✓, vet ✓, lint ✓ (v2.13.2). Plus the real-binary table above, run against live listeners.

New tests in cmd/suggest_test.go:

• TestEditDistance, including the swap and unicode cases.
• TestSuggestName: short and far queries, ties, the ? placeholder, and kill's filter for docker-proxy, containers and Compose services.
• TestSuggestCommand, including a synthetic tie.
• TestArgsError: every message, plus a check that cobra's "arg(s)" wording never leaks.

Risk

Tier: risky, because cmd/root.go holds the exit-code mapping. No exit code or stdout output changes; only stderr text does, for argument-count errors, unknown commands, an unknown completion shell, and find/kill misses.
Rollback: revert the squash commit.

A fresh-context review blocked the first commit, rightly. It worked out whether an argument is required from the usage text, and completion [bash|zsh|…] actually needs exactly one, so ports completion still showed cobra's wording. Now the command's own validator decides.

Its should-fixes are also in:

• kill suggested names it can't match;
• Compose service names weren't offered;
• a tie between two commands still picked one.

A re-review said ok to ship. Its two nits are the last commit: compare commands rather than spellings, so a name and its own alias can't tie, and fix a comment.

Notes for the release

Error messages say what's missing, with an example. Mistyped commands and names get a "did you mean" suggestion. Exit codes are unchanged.

---

Generated by Claude Code