File size: 5,300 Bytes
fc93158 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 | import type { Command } from "commander";
import { resolveCommitHash } from "../../infra/git-commit.js";
import { formatDocsLink } from "../../terminal/links.js";
import { isRich, theme } from "../../terminal/theme.js";
import { escapeRegExp } from "../../utils.js";
import { hasFlag, hasRootVersionAlias } from "../argv.js";
import { formatCliBannerLine, hasEmittedCliBanner } from "../banner.js";
import { replaceCliName, resolveCliDisplayName, resolveCliName } from "../cli-name.js";
import { CLI_LOG_LEVEL_VALUES, parseCliLogLevelOption } from "../log-level-option.js";
import { getCoreCliCommandsWithSubcommands } from "./command-registry.js";
import type { ProgramContext } from "./context.js";
import { getSubCliCommandsWithSubcommands } from "./register.subclis.js";
const ROOT_COMMANDS_WITH_SUBCOMMANDS = new Set([
...getCoreCliCommandsWithSubcommands(),
...getSubCliCommandsWithSubcommands(),
]);
const ROOT_COMMANDS_HINT =
"Hint: commands suffixed with * have subcommands. Run <command> --help for details.";
const EXAMPLES = [
["openskynet models --help", "Show detailed help for the models command."],
[
"openskynet channels login --verbose",
"Link personal WhatsApp Web and show QR + connection logs.",
],
[
'openskynet message send --target +15555550123 --message "Hi" --json',
"Send via your web session and print JSON result.",
],
["openskynet gateway --port 18789", "Run the WebSocket Gateway locally."],
[
"openskynet --dev gateway",
"Run a dev Gateway (isolated state/config) on ws://127.0.0.1:19001.",
],
["openskynet gateway --force", "Kill anything bound to the default gateway port, then start it."],
["openskynet gateway ...", "Gateway control via WebSocket."],
[
'openskynet agent --to +15555550123 --message "Run summary" --deliver',
"Talk directly to the agent using the Gateway; optionally send the WhatsApp reply.",
],
[
'openskynet message send --channel telegram --target @mychat --message "Hi"',
"Send via your Telegram bot.",
],
] as const;
export function configureProgramHelp(program: Command, ctx: ProgramContext) {
const cliName = resolveCliName();
const cliDisplayName = resolveCliDisplayName();
const cliNamePattern = escapeRegExp(cliName);
program
.name(cliName)
.description("")
.version(ctx.programVersion)
.option(
"--dev",
"Dev profile: isolate state/config, default gateway port 19001, and shift derived ports (browser/canvas)",
)
.option(
"--profile <name>",
"Use a named profile (isolates state/config under a profile-specific directory)",
)
.option(
"--log-level <level>",
`Global log level override for file + console (${CLI_LOG_LEVEL_VALUES})`,
parseCliLogLevelOption,
);
program.option("--no-color", "Disable ANSI colors", false);
program.helpOption("-h, --help", "Display help for command");
program.helpCommand("help [command]", "Display help for command");
program.configureHelp({
// sort options and subcommands alphabetically
sortSubcommands: true,
sortOptions: true,
optionTerm: (option) => theme.option(option.flags),
subcommandTerm: (cmd) => {
const isRootCommand = cmd.parent === program;
const hasSubcommands = isRootCommand && ROOT_COMMANDS_WITH_SUBCOMMANDS.has(cmd.name());
return theme.command(hasSubcommands ? `${cmd.name()} *` : cmd.name());
},
});
const formatHelpOutput = (str: string) => {
let output = str;
const isRootHelp = new RegExp(
`^Usage:\\s+${cliNamePattern}\\s+\\[options\\]\\s+\\[command\\]\\s*$`,
"m",
).test(output);
if (isRootHelp && /^Commands:/m.test(output)) {
output = output.replace(/^Commands:/m, `Commands:\n ${theme.muted(ROOT_COMMANDS_HINT)}`);
}
return output
.replace(/^Usage:/gm, theme.heading("Usage:"))
.replace(/^Options:/gm, theme.heading("Options:"))
.replace(/^Commands:/gm, theme.heading("Commands:"));
};
program.configureOutput({
writeOut: (str) => {
process.stdout.write(formatHelpOutput(str));
},
writeErr: (str) => {
process.stderr.write(formatHelpOutput(str));
},
outputError: (str, write) => write(theme.error(str)),
});
if (
hasFlag(process.argv, "-V") ||
hasFlag(process.argv, "--version") ||
hasRootVersionAlias(process.argv)
) {
const commit = resolveCommitHash({ moduleUrl: import.meta.url });
console.log(
commit
? `${cliDisplayName} ${ctx.programVersion} (${commit})`
: `${cliDisplayName} ${ctx.programVersion}`,
);
process.exit(0);
}
program.addHelpText("beforeAll", () => {
if (hasEmittedCliBanner()) {
return "";
}
const rich = isRich();
const line = formatCliBannerLine(ctx.programVersion, { richTty: rich });
return `\n${line}\n`;
});
const fmtExamples = EXAMPLES.map(
([cmd, desc]) => ` ${theme.command(replaceCliName(cmd, cliName))}\n ${theme.muted(desc)}`,
).join("\n");
program.addHelpText("afterAll", ({ command }) => {
if (command !== program) {
return "";
}
const docs = formatDocsLink("/cli", "docs.openclaw.ai/cli");
return `\n${theme.heading("Examples:")}\n${fmtExamples}\n\n${theme.muted("Docs:")} ${docs}\n`;
});
}
|