import { formatCliCommand } from "../command-format.js";

import { getCoreCliCommandNames } from "./core-command-descriptors.js";

import { getSubCliEntries } from "./subcli-descriptors.js";

const EXPLICIT_COMMAND_ALIASES = new Map<string, string>([

["upgrade", "update"],

["udpate", "update"],

]);

const MAX_SUGGESTIONS = 3;

function uniqueSortedCommandNames(commands: Iterable<string>): string[] {

return [...new Set([...commands].filter(Boolean))].toSorted((left, right) =>

left.localeCompare(right),

);

}

export function getKnownCliCommandNames(): string[] {

return uniqueSortedCommandNames([

...getCoreCliCommandNames(),

...getSubCliEntries().map((entry) => entry.name),

]);

}

export function levenshteinDistance(left: string, right: string): number {

if (left === right) {

return 0;

}

if (left.length === 0) {

return right.length;

}

if (right.length === 0) {

return left.length;

}

let previous = Array.from({ length: right.length + 1 }, (_, index) => index);

let current = Array.from<number>({ length: right.length + 1 });

for (let leftIndex = 0; leftIndex < left.length; leftIndex += 1) {

current[0] = leftIndex + 1;

for (let rightIndex = 0; rightIndex < right.length; rightIndex += 1) {

const substitutionCost = left[leftIndex] === right[rightIndex] ? 0 : 1;

current[rightIndex + 1] = Math.min(

current[rightIndex] + 1,

previous[rightIndex + 1] + 1,

previous[rightIndex] + substitutionCost,

);

}

[previous, current] = [current, previous];

}

return previous[right.length] ?? 0;

}

export function suggestCliCommands(

input: string,

candidates: Iterable<string> = getKnownCliCommandNames(),

): string[] {

const normalizedInput = input.trim().toLowerCase();

if (!normalizedInput) {

return [];

}

const knownCommands = uniqueSortedCommandNames(candidates);

const explicitAlias = EXPLICIT_COMMAND_ALIASES.get(normalizedInput);

if (explicitAlias && knownCommands.includes(explicitAlias)) {

return [explicitAlias];

}

const maxDistance = Math.max(1, Math.floor(normalizedInput.length * 0.4));

return knownCommands

.map((command) => ({ command, distance: levenshteinDistance(normalizedInput, command) }))

.filter(({ command, distance }) => command !== normalizedInput && distance <= maxDistance)

.toSorted(

(left, right) => left.distance - right.distance || left.command.localeCompare(right.command),

)

.slice(0, MAX_SUGGESTIONS)

.map(({ command }) => command);

}

export function formatCliCommandSuggestions(input: string): string | undefined {

const suggestions = suggestCliCommands(input);

if (suggestions.length === 0) {

return undefined;

}

const commandLines = suggestions

.map((command) => ` ${formatCliCommand(`openclaw ${command}`)}`)

.join("\n");

return `Did you mean this?\n${commandLines}`;

}

);

});

it("suggests close known commands for unknown commands", () => {

const output = formatCliParseErrorOutput("error: unknown command 'upate'\n", {

argv: ["node", "openclaw", "upate"],

});

expect(output).toBe(

'OpenClaw does not know the command "upate".\nDid you mean this?\n openclaw update\nTry: openclaw --help\nPlugin command? openclaw plugins list\nDocs: https://docs.openclaw.ai/cli\n',

);

});

it("suggests explicit aliases for common adjacent terminology", () => {

const output = formatCliParseErrorOutput("error: unknown command 'upgrade'\n", {

argv: ["node", "openclaw", "upgrade"],

});

expect(output).toContain("Did you mean this?\n openclaw update\n");

});

it("preserves active profile context in command suggestions", () => {

const originalProfile = process.env.OPENCLAW_PROFILE;

process.env.OPENCLAW_PROFILE = "work";

try {

const output = formatCliParseErrorOutput("error: unknown command 'doctr'\n", {

argv: ["node", "openclaw", "doctr"],

});

expect(output).toContain("Did you mean this?\n openclaw --profile work doctor\n");

} finally {

if (originalProfile === undefined) {

delete process.env.OPENCLAW_PROFILE;

} else {

process.env.OPENCLAW_PROFILE = originalProfile;

}

}

});

it("points unknown options at the active command help", () => {

const output = formatCliParseErrorOutput("error: unknown option '--wat'\n", {

argv: ["node", "openclaw", "channels", "status", "--wat"],

import { theme } from "../../../packages/terminal-core/src/theme.js";

import { getCommandPathWithRootOptions } from "../argv.js";

import { formatCliCommand } from "../command-format.js";

import { formatCliCommandSuggestions } from "./command-suggestions.js";

type FormatCliParseErrorOptions = {

argv?: string[];

const command = unknownCommand[1] ?? "";

return lines(

theme.error(`OpenClaw does not know the command ${quote(command)}.`),

formatCliCommandSuggestions(command),

formatHelpHint(options.argv, { root: true }),

`${theme.muted("Plugin command?")} ${theme.command(formatCliCommand("openclaw plugins list"))}`,

formatDocsHint(),

expect(registerPluginCliCommandsFromValidatedConfigMock).not.toHaveBeenCalled();

});

it("suggests close known commands for unowned command roots before proxy startup", async () => {

await expect(runCli(["node", "openclaw", "upate"])).rejects.toThrow(

"Did you mean this?\n openclaw update",

);

expect(startProxyMock).not.toHaveBeenCalled();

expect(tryRouteCliMock).not.toHaveBeenCalled();

expect(buildProgramMock).not.toHaveBeenCalled();

expect(registerPluginCliCommandsFromValidatedConfigMock).not.toHaveBeenCalled();

});

it("keeps suggestions out of plugin-policy diagnostics", async () => {

resolveManifestCommandAliasOwnerMock.mockReturnValueOnce({

pluginId: "codex",

kind: "runtime-slash",

cliCommand: "plugins",

});

let error: unknown;

try {

await runCli(["node", "openclaw", "codex"]);

} catch (caught) {

error = caught;

}

expect(error).toBeInstanceOf(Error);

expect((error as Error).message).toContain("runtime slash command");

expect((error as Error).message).toContain("/codex");

expect((error as Error).message).not.toContain("Did you mean this?");

expect(startProxyMock).not.toHaveBeenCalled();

expect(tryRouteCliMock).not.toHaveBeenCalled();

expect(buildProgramMock).not.toHaveBeenCalled();

expect(registerPluginCliCommandsFromValidatedConfigMock).not.toHaveBeenCalled();

});

it("rejects unowned command roots even when --help is appended (regression for #81077)", async () => {

await expect(runCli(["node", "openclaw", "foo", "--help"])).rejects.toThrow(

'No built-in command or plugin CLI metadata owns "foo"',

} from "./gateway-run-argv.js";

import { hasJsonOutputFlag, withConsoleLogsRoutedToStderrForJson } from "./json-output-mode.js";

import { applyCliProfileEnv, parseCliProfileArgs } from "./profile.js";

import { formatCliCommandSuggestions } from "./program/command-suggestions.js";

import { getCoreCliCommandNames } from "./program/core-command-descriptors.js";

import { getSubCliEntries } from "./program/subcli-descriptors.js";

import {

const { resolveManifestCommandAliasOwner, resolveManifestToolOwner } =

await loadManifestCommandAliasesRuntimeModule();

const cliCommandSurfaceOwner = await resolveCliCommandSurfaceOwner(params);

return (

resolveMissingPluginCommandMessageFromPolicy(params.primary, params.config, {

const pluginPolicyMessage = resolveMissingPluginCommandMessageFromPolicy(

params.primary,

params.config,

{

resolveCommandAliasOwner: resolveManifestCommandAliasOwner,

resolveToolOwner: resolveManifestToolOwner,

resolveCliCommandSurfaceOwner: () => cliCommandSurfaceOwner,

}) ??

`Unknown command: openclaw ${params.primary}. No built-in command or plugin CLI metadata owns "${params.primary}".`

},

);

if (pluginPolicyMessage) {

return pluginPolicyMessage;

}

const suggestion = formatCliCommandSuggestions(params.primary);

return [

`Unknown command: openclaw ${params.primary}. No built-in command or plugin CLI metadata owns "${params.primary}".`,

suggestion,

]

.filter(Boolean)

.join("\n");

}

async function bootstrapCliProxyCaptureAndDispatcher(