PR #84036: feat(cli): suggest closest command for unknown subcommands (#83999)

• Repository: openclaw/openclaw
• Author: 0xghost42
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/84036

Description (problem / solution / changelog)

Closes #83999.

Summary

`openclaw upate` and `openclaw upgrade` previously failed with a generic `OpenClaw does not know the command "upate".` and left the user to inspect `openclaw --help` manually. This change appends npm-style `Did you mean this?` suggestions, computed from Levenshtein distance against the registered root commands plus a tight explicit alias map for terminology that doesn't fall out of edit distance (`upgrade -> update`, `remove -> uninstall`, `rm -> uninstall`, `ls -> list`, `ping -> doctor`).

Output shapes:

``` $ openclaw upate OpenClaw does not know the command "upate". Did you mean this? openclaw update Try: openclaw --help Plugin command? openclaw plugins list Docs: https://docs.openclaw.ai/cli ```

``` $ openclaw upgrade OpenClaw does not know the command "upgrade". Did you mean this? openclaw update ... ```

``` $ openclaw zzqwerty # no suggestion when nothing is close OpenClaw does not know the command "zzqwerty". Try: openclaw --help ... ```

Design

• `suggestClosestCommand` is exported from `src/cli/program/error-output.ts` and takes `(unknown, known[])`. Known commands are passed via the new `knownCommands` option on `formatCliParseErrorOptions`.
• Explicit aliases win over edit distance — `upgrade -> update` is canonical even when other short roots score closer numerically.
• Alias target must exist in `knownCommands` so the suggester can't invent a command that this build doesn't actually have.
• npm-style threshold: distance must be `<= floor(input.length * 0.4)` (min 1). Keeps `zzqwerty` from misleadingly resolving to a 4-character root.
• Two-row Levenshtein, `O(min(a,b))` memory, `O(a*b)` time. CLI roots are short, so this is fine.
• No auto-correct, no auto-run: just an appended hint, same as the existing plugin hint.
• Wired into the one caller (`src/cli/program/help.ts:108`) via `program.commands.map((cmd) => cmd.name())`, so the catalog stays in sync with whatever `openclaw --help` lists. When `knownCommands` is omitted (legacy callers / tests) the suggester is a no-op — behavior is unchanged.

Real behavior proof

Behavior addressed: unknown root commands now append `Did you mean this?` with the closest registered command (or alias target) when the distance is small enough.

Real environment tested: darwin / arm64 / Node 22.21.1, openclaw source tree at HEAD of branch above.

Exact steps or command run after this patch:

``` node scripts/run-vitest.mjs src/cli/program/error-output.test.ts ./node_modules/.bin/oxlint --type-aware src/cli/program/error-output.ts src/cli/program/error-output.test.ts src/cli/program/help.ts ```

Evidence after fix:

``` $ node scripts/run-vitest.mjs src/cli/program/error-output.test.ts RUN v4.1.6 /Users/harshkumarkaithwas/Desktop/openclaw

Test Files 1 passed (1) Tests 13 passed (13)

$ ./node_modules/.bin/oxlint --type-aware src/cli/program/error-output.ts src/cli/program/error-output.test.ts src/cli/program/help.ts Found 0 warnings and 0 errors. ```

Observed result after fix: `formatCliParseErrorOutput` now emits `Did you mean this?\n openclaw update\n` between the unknown-command error line and the `Try:` hint when (a) a typo is within edit-distance threshold OR (b) the input matches an entry in the explicit alias map AND the alias target is registered.

What was not tested: live binary spawn against a built `openclaw` CLI — covered transitively by the existing parse-error round-trip and `run-main.exit.test.ts` suite, which both call the same Commander `outputError` path.

Coverage

Unit tests in `src/cli/program/error-output.test.ts`:

Notes

• No public API change; `knownCommands` is additive on an existing options bag.
• Local lint+format wrappers (`node scripts/run-oxlint.mjs`, `pnpm format`) hit a pre-existing dts boundary failure on `@openclaw/proxyline` unrelated to this PR; ran `./node_modules/.bin/oxlint --type-aware` and `./node_modules/.bin/oxfmt --write` directly on the touched files.

Changed files

• src/cli/program/error-output.test.ts (modified, +69/-1)
• src/cli/program/error-output.ts (modified, +86/-0)
• src/cli/program/help.ts (modified, +10/-1)