From 83729b49585e2b83f65a63fffa5ae07d78c08447 Mon Sep 17 00:00:00 2001 From: Senthil Ravichandran Date: Wed, 19 Aug 2026 18:08:53 -0700 Subject: [PATCH 1/3] fix(cli): bound docs parity process starts Signed-off-by: Senthil Ravichandran --- src/lib/cli/argv-normalizer.test.ts | 6 + src/lib/cli/argv-normalizer.ts | 6 + src/lib/cli/command-registry.ts | 22 +++ src/lib/cli/public-dispatch.ts | 8 ++ test/e2e/e2e-cloud-experimental/check-docs.sh | 128 +++++++++--------- .../cli/public-cli-contracts.test.ts | 35 ++++- 6 files changed, 141 insertions(+), 64 deletions(-) diff --git a/src/lib/cli/argv-normalizer.test.ts b/src/lib/cli/argv-normalizer.test.ts index 07bc742be3d..850bda285a1 100644 --- a/src/lib/cli/argv-normalizer.test.ts +++ b/src/lib/cli/argv-normalizer.test.ts @@ -24,6 +24,12 @@ describe("normalizeArgv", () => { expect( normalizeArgv(["--dump-commands"], { globalCommands, isSandboxConnectFlag: isConnectFlag }), ).toEqual({ kind: "dumpCommands" }); + expect( + normalizeArgv(["--dump-command-flags"], { + globalCommands, + isSandboxConnectFlag: isConnectFlag, + }), + ).toEqual({ kind: "dumpCommandFlags" }); }); it("normalizes global commands", () => { diff --git a/src/lib/cli/argv-normalizer.ts b/src/lib/cli/argv-normalizer.ts index ee9e73c9116..cca96b9cedc 100644 --- a/src/lib/cli/argv-normalizer.ts +++ b/src/lib/cli/argv-normalizer.ts @@ -3,6 +3,7 @@ export type NormalizedRootHelpArgv = { kind: "rootHelp" }; export type NormalizedDumpCommandsArgv = { kind: "dumpCommands" }; +export type NormalizedDumpCommandFlagsArgv = { kind: "dumpCommandFlags" }; export type NormalizedGlobalArgv = { kind: "global"; command: string; args: string[] }; export type NormalizedSandboxArgv = { kind: "sandbox"; @@ -15,6 +16,7 @@ export type NormalizedSandboxArgv = { export type NormalizedArgv = | NormalizedRootHelpArgv | NormalizedDumpCommandsArgv + | NormalizedDumpCommandFlagsArgv | NormalizedGlobalArgv | NormalizedSandboxArgv; @@ -34,6 +36,10 @@ export function normalizeArgv(argv: readonly string[], opts: NormalizeArgvOption return { kind: "dumpCommands" }; } + if (cmd === "--dump-command-flags") { + return { kind: "dumpCommandFlags" }; + } + if (opts.globalCommands.has(cmd)) { return { kind: "global", command: cmd, args }; } diff --git a/src/lib/cli/command-registry.ts b/src/lib/cli/command-registry.ts index e400dbedf73..e24e3e2b44b 100644 --- a/src/lib/cli/command-registry.ts +++ b/src/lib/cli/command-registry.ts @@ -121,6 +121,28 @@ export function canonicalUsageList(): string[] { .sort(); } +type PublicFlagMetadata = { + allowNo?: boolean; + hidden?: boolean; +}; + +/** Sorted public long flags keyed by each visible canonical usage string. */ +export function canonicalCommandFlagLines(): string[] { + const metadata = getRegisteredOclifCommandsMetadata(); + return visibleCommands() + .map((command) => { + const flags = Object.entries(metadata[command.commandId]?.flags ?? {}) + .flatMap(([name, value]) => { + const flag = value as PublicFlagMetadata; + if (flag.hidden) return []; + return flag.allowNo ? [`--${name}`, `--no-${name}`] : [`--${name}`]; + }) + .sort(); + return `${command.usage}\t${flags.join(" ")}`; + }) + .sort(); +} + /** * First token(s) after "nemoclaw" for each global command. * diff --git a/src/lib/cli/public-dispatch.ts b/src/lib/cli/public-dispatch.ts index 2e58035d966..49dfce8193f 100644 --- a/src/lib/cli/public-dispatch.ts +++ b/src/lib/cli/public-dispatch.ts @@ -16,6 +16,7 @@ const { CLI_NAME } = require("./branding"); const { help } = require("../actions/root-help"); const { runOclifArgv, runOclifCommandById } = require("./oclif-runner"); const { + canonicalCommandFlagLines, canonicalUsageList, globalCommandTokens, sandboxActionTokensForDispatch, @@ -362,6 +363,11 @@ async function dispatchNormalizedArgv(normalized: NormalizedArgv, argv: string[] return; } + if (normalized.kind === "dumpCommandFlags") { + canonicalCommandFlagLines().forEach((line: string) => console.log(line)); + return; + } + if (normalized.kind === "global") { await dispatchGlobalArgv(normalized); return; @@ -482,6 +488,8 @@ export async function dispatchCli(argv: string[] = process.argv.slice(2)): Promi argv.includes("--help") || argv.includes("-h") || argv.includes("--version") || + argv[0] === "--dump-commands" || + argv[0] === "--dump-command-flags" || argv[0] === "version" || argv[0] === "help" || argv[0] === "completion"; diff --git a/test/e2e/e2e-cloud-experimental/check-docs.sh b/test/e2e/e2e-cloud-experimental/check-docs.sh index 3f20bd38e8f..fef53d74426 100755 --- a/test/e2e/e2e-cloud-experimental/check-docs.sh +++ b/test/e2e/e2e-cloud-experimental/check-docs.sh @@ -219,23 +219,24 @@ JSON log "[cli] command-level parity OK (${_n_help} nemoclaw command(s))" # ── Phase 3/3: flag-level parity (NemoClaw#3224) ────────────────────────── - # For each command, run its `--help`, extract every long-form flag mentioned, - # and confirm each appears within that command's own section in + # Read the compiled oclif metadata that renders `--help`, then confirm each + # public long-form flag appears within that command's own section in # commands.mdx (between its `### \`nemoclaw \`` heading and the next - # ### heading). Two help formats coexist: oclif global commands use a - # USAGE/FLAGS layout; `nemoclaw ...` commands use a custom - # Options: section. Greping the full help output handles both formats. + # ### heading). Commands with custom help fall back to their rendered output. + # All other commands avoid a separate cold CLI start. # Section-scoped grep avoids false negatives where a flag like `--yes` # appears in many sections but is missing from the one being audited. # Word-boundary regex avoids false positives where `--yes` is contained # in `--yes-i-accept-third-party-software`. Skips global -h/--help/--version. # - # The check runs with an isolated HOME that contains a fake - # `placeholder-sandbox` registry entry. That keeps CI deterministic and lets - # sandbox-scoped commands print `--help` without touching the user's real - # ~/.nemoclaw state. log "[cli] phase 3/3: flag-level parity" + if ! HOME="$_cli_home" "$NODE" "$CLI_JS" --dump-command-flags >"$_tmp/flags.txt" 2>"$_tmp/flags.err"; then + cat "$_tmp/flags.err" >&2 + rm -rf "$_tmp" + return 1 + fi + # Awk extractor: print lines belonging to the section whose heading # canonicalizes to after the same trailing-placeholder strip phase 2 # applies (`### \`nemoclaw foo \`` → `nemoclaw foo`). Stops at the @@ -303,8 +304,6 @@ JSON next; } if (/^\s*$/) { - # Oclif separates flag entries with blank lines, while the custom - # one-line Usage format uses one to end its usage synopsis. $mode = "" if $mode eq "usage"; next; } @@ -320,40 +319,23 @@ JSON # `nemoclaw onboard`) that is iterated separately. Re-invoking them # with `--help` would just trigger flag-value parsing errors. case "$cmd_line" in *" --"*) continue ;; esac - # `--dump-commands` lines start with `nemoclaw `; strip that since we - # re-invoke via `node bin/nemoclaw.js`. Then replace with a - # sandbox name that passes name validation (lowercase, starts with - # letter, only letters/digits/hyphens — underscores are rejected). - local invoke - invoke="${cmd_line#nemoclaw }" - invoke="${invoke///placeholder-sandbox}" - # Read into an array so each space-separated token is a distinct argv - # element to node — avoids SC2086 and any quoting surprises. - local -a _invoke_args - read -ra _invoke_args <<<"$invoke" - # Redirect stdin to /dev/null. The outer `while read` is consuming - # `$_tmp/help.txt` via `done <` redirection; any inner command that - # touches stdin (some node startup paths do) would eat subsequent - # lines, silently truncating the iteration. Negative-tested by - # mutating commands.mdx and confirming drift is now reported. - # - # Capture exit code separately so a real failure (broken command path, - # crashed loader, etc.) propagates instead of being swallowed by - # `|| true`. - local _help_text _help_err _help_rc=0 - _help_err="$(mktemp)" - _help_text="$(HOME="$_cli_home" "$NODE" "$CLI_JS" "${_invoke_args[@]}" --help "$_help_err")" || _help_rc=$? - if [[ "$_help_rc" -ne 0 ]]; then - cat "$_help_err" >&2 - rm -f "$_help_err" + local _flag_line _flag_rc=0 + _flag_line="$(LC_ALL=C awk -F '\t' -v target="$cmd_line" ' + $1 == target { + print substr($0, index($0, "\t") + 1) + found = 1 + exit + } + END { if (!found) exit 1 } + ' "$_tmp/flags.txt")" || _flag_rc=$? + if [[ "$_flag_rc" -ne 0 ]]; then + echo "check-docs: [cli] missing compiled flag metadata for '$cmd_line'" >&2 rm -rf "$_tmp" return 1 fi - rm -f "$_help_err" - [[ -z "$_help_text" ]] && continue local _flags - _flags="$(extract_help_flags "$_help_text")" + _flags="$(printf '%s\n' "$_flag_line" | tr ' ' '\n' | grep -v '^$' | LC_ALL=C sort -u || true)" [[ -z "$_flags" ]] && continue local _section @@ -364,27 +346,8 @@ JSON _section="$(cat "$COMMANDS_MD")" fi - while IFS= read -r flag; do - [[ -z "$flag" ]] && continue - case "$flag" in --help | --version) continue ;; esac - # Word-boundary regex: treat letters/digits/_/- as continuation chars - # so `--yes` does not match inside `--yes-i-accept-third-party-software`. - local _pat="(^|[^a-zA-Z0-9_-])${flag}([^a-zA-Z0-9_-]|$)" - if ! grep -qE -- "$_pat" <<<"$_section"; then - echo "check-docs: [cli] flag $flag (from \`$cmd_line --help\`) not in '$cmd_line' section of $COMMANDS_MD" >&2 - _flag_drift=1 - fi - done <<<"$_flags" - - # Reverse direction: extract long flags mentioned in the doc section - # and confirm each appears in the actual --help. Catches stale docs - # (flag removed from CLI but still listed in commands.mdx). - # - # Scoping rule: inside fenced code blocks (where USAGE lines live like - # `[--non-interactive]`), any `--foo` counts. Outside fences, only - # backtick-bounded `\`--foo\`` mentions count, so prose references to - # other tools (e.g. `\`openshell sandbox create --from\``) don't get - # mistaken for nemoclaw flag documentation. + # Extract documented flags before selecting the help source. Commands + # that implement custom help can advertise flags outside oclif metadata. local _doc_flags _doc_flags="$( printf '%s\n' "$_section" \ @@ -399,6 +362,49 @@ JSON | grep -vxE -- '--help|--version' \ | LC_ALL=C sort -u || true )" + + local _needs_rendered_help=0 + while IFS= read -r flag; do + [[ -z "$flag" ]] && continue + if ! grep -qxF -- "$flag" <<<"$_flags"; then + _needs_rendered_help=1 + break + fi + done <<<"$_doc_flags" + + if [[ "$_needs_rendered_help" -eq 1 ]]; then + local invoke + invoke="${cmd_line#nemoclaw }" + invoke="${invoke///placeholder-sandbox}" + local -a _invoke_args + read -ra _invoke_args <<<"$invoke" + local _help_text _help_rc=0 + _help_text="$(HOME="$_cli_home" "$NODE" "$CLI_JS" "${_invoke_args[@]}" --help "$_tmp/command-help.err")" || _help_rc=$? + if [[ "$_help_rc" -ne 0 ]]; then + cat "$_tmp/command-help.err" >&2 + rm -rf "$_tmp" + return 1 + fi + _flags="$(extract_help_flags "$_help_text")" + # Preserve the existing custom-help contract: a help screen with no + # parseable usage or flag section does not participate in flag parity. + [[ -z "$_flags" ]] && continue + fi + + while IFS= read -r flag; do + [[ -z "$flag" ]] && continue + case "$flag" in --help | --version) continue ;; esac + # Word-boundary regex: treat letters/digits/_/- as continuation chars + # so `--yes` does not match inside `--yes-i-accept-third-party-software`. + local _pat="(^|[^a-zA-Z0-9_-])${flag}([^a-zA-Z0-9_-]|$)" + if ! grep -qE -- "$_pat" <<<"$_section"; then + echo "check-docs: [cli] flag $flag (from \`$cmd_line --help\`) not in '$cmd_line' section of $COMMANDS_MD" >&2 + _flag_drift=1 + fi + done <<<"$_flags" + + # Reverse direction catches stale docs after the metadata or rendered-help + # selection above establishes the command's public flag set. while IFS= read -r flag; do [[ -z "$flag" ]] && continue if ! grep -qxF -- "$flag" <<<"$_flags"; then diff --git a/test/package-contract/cli/public-cli-contracts.test.ts b/test/package-contract/cli/public-cli-contracts.test.ts index 0c637f0b823..3ec5c0f1cdc 100644 --- a/test/package-contract/cli/public-cli-contracts.test.ts +++ b/test/package-contract/cli/public-cli-contracts.test.ts @@ -29,16 +29,27 @@ describe("public compiled CLI contracts", () => { it("keeps compiled CLI commands aligned with their documentation headings (#7616)", { timeout: 150_000, }, () => { - // `npm run test:package` builds the CLI before this project, so the shim - // exercises the same compiled entrypoint shipped by the package. + // `npm run test:package` builds the CLI before this project. The Node.js + // shim records every compiled entrypoint invocation so this check cannot + // return to one cold CLI start for each documented command. const fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-docs-cli-parity-")); const binDir = path.join(fixtureRoot, "bin"); const shim = path.join(binDir, "nemoclaw"); + const nodeShim = path.join(binDir, "node"); + const nodeInvocationLog = path.join(fixtureRoot, "node-invocations.log"); fs.mkdirSync(binDir, { recursive: true }); fs.writeFileSync( shim, `#!/usr/bin/env bash exec ${JSON.stringify(process.execPath)} ${JSON.stringify(CLI_ENTRYPOINT)} "$@" +`, + { mode: 0o755 }, + ); + fs.writeFileSync( + nodeShim, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >>${JSON.stringify(nodeInvocationLog)} +exec ${JSON.stringify(process.execPath)} "$@" `, { mode: 0o755 }, ); @@ -51,7 +62,7 @@ exec ${JSON.stringify(process.execPath)} ${JSON.stringify(CLI_ENTRYPOINT)} "$@" ...process.env, CHECK_DOC_LINKS_REMOTE: "0", HOME: fixtureRoot, - NODE: process.execPath, + NODE: nodeShim, PATH: `${binDir}${path.delimiter}${process.env.PATH ?? ""}`, }, killSignal: "SIGKILL", @@ -63,6 +74,24 @@ exec ${JSON.stringify(process.execPath)} ${JSON.stringify(CLI_ENTRYPOINT)} "$@" expect(result.status, `${result.stdout}\n${result.stderr}`).toBe(0); expect(result.stdout).toContain("check-docs: running: [cli]"); expect(result.stdout).toContain("command-level parity OK"); + expect(result.stdout).toContain("flag-level parity OK"); + expect(fs.readFileSync(nodeInvocationLog, "utf-8").trim().split("\n")).toEqual([ + `${CLI_ENTRYPOINT} --dump-commands`, + `${CLI_ENTRYPOINT} --dump-command-flags`, + `${CLI_ENTRYPOINT} placeholder-sandbox agent --help`, + `${CLI_ENTRYPOINT} placeholder-sandbox agents add --help`, + `${CLI_ENTRYPOINT} placeholder-sandbox agents apply --help`, + `${CLI_ENTRYPOINT} placeholder-sandbox agents delete --help`, + `${CLI_ENTRYPOINT} placeholder-sandbox agents list --help`, + `${CLI_ENTRYPOINT} placeholder-sandbox mcp add --help`, + `${CLI_ENTRYPOINT} placeholder-sandbox mcp list --help`, + `${CLI_ENTRYPOINT} placeholder-sandbox mcp remove --help`, + `${CLI_ENTRYPOINT} placeholder-sandbox mcp status --help`, + `${CLI_ENTRYPOINT} placeholder-sandbox sessions --help`, + `${CLI_ENTRYPOINT} placeholder-sandbox sessions list --help`, + `${CLI_ENTRYPOINT} uninstall --help`, + `${path.join(REPO_ROOT, "dist", "nemoclaw.js")} internal uninstall run-plan --help`, + ]); } finally { fs.rmSync(fixtureRoot, { force: true, recursive: true }); } From 1a4a8949eb5063ab256dc4d995146c30697ca1ca Mon Sep 17 00:00:00 2001 From: Senthil Ravichandran Date: Wed, 19 Aug 2026 19:05:52 -0700 Subject: [PATCH 2/3] fix(cli): preserve custom-help flag parity Signed-off-by: Senthil Ravichandran --- test/e2e/e2e-cloud-experimental/check-docs.sh | 2 +- test/package-contract/cli/public-cli-contracts.test.ts | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/test/e2e/e2e-cloud-experimental/check-docs.sh b/test/e2e/e2e-cloud-experimental/check-docs.sh index fef53d74426..c6e8f6cc87e 100755 --- a/test/e2e/e2e-cloud-experimental/check-docs.sh +++ b/test/e2e/e2e-cloud-experimental/check-docs.sh @@ -336,7 +336,6 @@ JSON local _flags _flags="$(printf '%s\n' "$_flag_line" | tr ' ' '\n' | grep -v '^$' | LC_ALL=C sort -u || true)" - [[ -z "$_flags" ]] && continue local _section _section="$(extract_md_section "$cmd_line" "$COMMANDS_MD")" @@ -362,6 +361,7 @@ JSON | grep -vxE -- '--help|--version' \ | LC_ALL=C sort -u || true )" + [[ -z "$_flags" && -z "$_doc_flags" ]] && continue local _needs_rendered_help=0 while IFS= read -r flag; do diff --git a/test/package-contract/cli/public-cli-contracts.test.ts b/test/package-contract/cli/public-cli-contracts.test.ts index 3ec5c0f1cdc..53334ec0c3e 100644 --- a/test/package-contract/cli/public-cli-contracts.test.ts +++ b/test/package-contract/cli/public-cli-contracts.test.ts @@ -45,10 +45,17 @@ exec ${JSON.stringify(process.execPath)} ${JSON.stringify(CLI_ENTRYPOINT)} "$@" `, { mode: 0o755 }, ); + // Remove ordinary metadata flags for one command whose documentation + // requires its custom rendered help. The fallback must still run. fs.writeFileSync( nodeShim, `#!/usr/bin/env bash printf '%s\\n' "$*" >>${JSON.stringify(nodeInvocationLog)} +if [[ "$2" == "--dump-command-flags" ]]; then + set -o pipefail + ${JSON.stringify(process.execPath)} "$@" | LC_ALL=C awk -F '\\t' '$1 == "nemoclaw agent" { print $1 "\\t"; next } { print }' + exit $? +fi exec ${JSON.stringify(process.execPath)} "$@" `, { mode: 0o755 }, From d200b5786ec9b9226dac57a990bc302229fa9ee7 Mon Sep 17 00:00:00 2001 From: Senthil Ravichandran Date: Wed, 19 Aug 2026 19:44:33 -0700 Subject: [PATCH 3/3] fix(cli): classify custom help for docs parity Signed-off-by: Senthil Ravichandran --- src/commands/sandbox/agent.ts | 1 + src/commands/sandbox/agents.ts | 1 + src/commands/sandbox/agents/add.ts | 1 + src/commands/sandbox/agents/apply.ts | 1 + src/commands/sandbox/agents/delete.ts | 1 + src/commands/sandbox/agents/list.ts | 1 + src/commands/sandbox/mcp.ts | 1 + src/commands/sandbox/sessions.ts | 1 + src/commands/sandbox/sessions/list.ts | 1 + src/commands/uninstall.ts | 1 + src/lib/cli/command-registry.ts | 5 +- .../cli/generate-oclif-metadata-manifest.ts | 1 + src/lib/cli/oclif-metadata.ts | 9 +- test/e2e/e2e-cloud-experimental/check-docs.sh | 31 ++-- .../cli/public-cli-contracts.test.ts | 173 +++++++++++------- 15 files changed, 152 insertions(+), 77 deletions(-) diff --git a/src/commands/sandbox/agent.ts b/src/commands/sandbox/agent.ts index b258f488003..ffac1b5d6de 100644 --- a/src/commands/sandbox/agent.ts +++ b/src/commands/sandbox/agent.ts @@ -7,6 +7,7 @@ import { NemoClawCommand } from "../../lib/cli/nemoclaw-oclif-command"; export default class SandboxAgentCommand extends NemoClawCommand { static id = "sandbox:agent"; + static customHelp = true; static strict = false; static summary = "Run one agent turn non-interactively in a sandbox"; static description = diff --git a/src/commands/sandbox/agents.ts b/src/commands/sandbox/agents.ts index ced6311ad74..daae1d885d3 100644 --- a/src/commands/sandbox/agents.ts +++ b/src/commands/sandbox/agents.ts @@ -6,6 +6,7 @@ import { NemoClawCommand } from "../../lib/cli/nemoclaw-oclif-command"; export default class SandboxAgentsCommand extends NemoClawCommand { static id = "sandbox:agents"; + static customHelp = true; static strict = false; static summary = "Manage OpenClaw agents inside a sandbox"; static description = diff --git a/src/commands/sandbox/agents/add.ts b/src/commands/sandbox/agents/add.ts index c84a9c723f6..de331de5c40 100644 --- a/src/commands/sandbox/agents/add.ts +++ b/src/commands/sandbox/agents/add.ts @@ -10,6 +10,7 @@ import { NemoClawCommand } from "../../../lib/cli/nemoclaw-oclif-command"; export default class SandboxAgentsAddCommand extends NemoClawCommand { static id = "sandbox:agents:add"; + static customHelp = true; static strict = false; static summary = "Add an OpenClaw agent inside a sandbox"; static description = diff --git a/src/commands/sandbox/agents/apply.ts b/src/commands/sandbox/agents/apply.ts index ac7ec05efc8..0db75130f16 100644 --- a/src/commands/sandbox/agents/apply.ts +++ b/src/commands/sandbox/agents/apply.ts @@ -37,6 +37,7 @@ function printApplyHelp(): void { export default class SandboxAgentsApplyCommand extends NemoClawCommand { static id = "sandbox:agents:apply"; + static customHelp = true; static strict = false; static summary = "Reconcile a sandbox's OpenClaw agents against a declarative manifest"; static description = diff --git a/src/commands/sandbox/agents/delete.ts b/src/commands/sandbox/agents/delete.ts index d5613803c34..009a7ea186e 100644 --- a/src/commands/sandbox/agents/delete.ts +++ b/src/commands/sandbox/agents/delete.ts @@ -10,6 +10,7 @@ import { NemoClawCommand } from "../../../lib/cli/nemoclaw-oclif-command"; export default class SandboxAgentsDeleteCommand extends NemoClawCommand { static id = "sandbox:agents:delete"; + static customHelp = true; static strict = false; static summary = "Delete an OpenClaw agent inside a sandbox"; static description = diff --git a/src/commands/sandbox/agents/list.ts b/src/commands/sandbox/agents/list.ts index c5d2027cc72..d92686d1183 100644 --- a/src/commands/sandbox/agents/list.ts +++ b/src/commands/sandbox/agents/list.ts @@ -10,6 +10,7 @@ import { NemoClawCommand } from "../../../lib/cli/nemoclaw-oclif-command"; export default class SandboxAgentsListCommand extends NemoClawCommand { static id = "sandbox:agents:list"; + static customHelp = true; static strict = false; static summary = "List OpenClaw agents configured in a sandbox"; static description = diff --git a/src/commands/sandbox/mcp.ts b/src/commands/sandbox/mcp.ts index c531cae658b..12a6782d330 100644 --- a/src/commands/sandbox/mcp.ts +++ b/src/commands/sandbox/mcp.ts @@ -5,6 +5,7 @@ import { NemoClawCommand } from "../../lib/cli/nemoclaw-oclif-command"; export default class SandboxMcpCommand extends NemoClawCommand { static id = "sandbox:mcp"; + static customHelp = true; static strict = false; static summary = "Manage MCP servers for a sandbox"; static description = diff --git a/src/commands/sandbox/sessions.ts b/src/commands/sandbox/sessions.ts index a1928029ba6..49cacb183b9 100644 --- a/src/commands/sandbox/sessions.ts +++ b/src/commands/sandbox/sessions.ts @@ -10,6 +10,7 @@ import { NemoClawCommand } from "../../lib/cli/nemoclaw-oclif-command"; export default class SandboxSessionsCommand extends NemoClawCommand { static id = "sandbox:sessions"; + static customHelp = true; static strict = false; static summary = "List conversation sessions in a sandbox"; static description = diff --git a/src/commands/sandbox/sessions/list.ts b/src/commands/sandbox/sessions/list.ts index 9bcbe8b7d34..7e89c4018ec 100644 --- a/src/commands/sandbox/sessions/list.ts +++ b/src/commands/sandbox/sessions/list.ts @@ -10,6 +10,7 @@ import { NemoClawCommand } from "../../../lib/cli/nemoclaw-oclif-command"; export default class SandboxSessionsListCommand extends NemoClawCommand { static id = "sandbox:sessions:list"; + static customHelp = true; static strict = false; static summary = "List conversation sessions in a sandbox"; static description = diff --git a/src/commands/uninstall.ts b/src/commands/uninstall.ts index e7fafb0b93c..526e82fdc51 100644 --- a/src/commands/uninstall.ts +++ b/src/commands/uninstall.ts @@ -10,6 +10,7 @@ import { buildVersionedUninstallUrl, runUninstallCommand } from "../lib/uninstal export default class UninstallCliCommand extends NemoClawCommand { static id = "uninstall"; + static customHelp = true; static strict = false; static summary = "Run uninstall.sh"; static description = "Run the local uninstall.sh script; remote fallback is disabled."; diff --git a/src/lib/cli/command-registry.ts b/src/lib/cli/command-registry.ts index e24e3e2b44b..8f87b5f03ee 100644 --- a/src/lib/cli/command-registry.ts +++ b/src/lib/cli/command-registry.ts @@ -126,7 +126,7 @@ type PublicFlagMetadata = { hidden?: boolean; }; -/** Sorted public long flags keyed by each visible canonical usage string. */ +/** Sorted public long flags and their help source keyed by canonical usage. */ export function canonicalCommandFlagLines(): string[] { const metadata = getRegisteredOclifCommandsMetadata(); return visibleCommands() @@ -138,7 +138,8 @@ export function canonicalCommandFlagLines(): string[] { return flag.allowNo ? [`--${name}`, `--no-${name}`] : [`--${name}`]; }) .sort(); - return `${command.usage}\t${flags.join(" ")}`; + const helpSource = metadata[command.commandId]?.customHelp === true ? "rendered" : "metadata"; + return `${command.usage}\t${helpSource}\t${flags.join(" ")}`; }) .sort(); } diff --git a/src/lib/cli/generate-oclif-metadata-manifest.ts b/src/lib/cli/generate-oclif-metadata-manifest.ts index 1ad991885c8..95418f59b8e 100644 --- a/src/lib/cli/generate-oclif-metadata-manifest.ts +++ b/src/lib/cli/generate-oclif-metadata-manifest.ts @@ -32,6 +32,7 @@ async function main(): Promise { for (const command of [...config.commands].sort((a, b) => a.id.localeCompare(b.id))) { const entry: SerializableCommandMetadata = {}; setIfDefined(entry, "args", command.args); + setIfDefined(entry, "customHelp", (command as { customHelp?: unknown }).customHelp); setIfDefined(entry, "description", command.description); setIfDefined(entry, "deprecationOptions", command.deprecationOptions); setIfDefined(entry, "examples", command.examples); diff --git a/src/lib/cli/oclif-metadata.ts b/src/lib/cli/oclif-metadata.ts index 8b2060a6627..ff7efcd5084 100644 --- a/src/lib/cli/oclif-metadata.ts +++ b/src/lib/cli/oclif-metadata.ts @@ -12,6 +12,8 @@ const GENERATED_METADATA_FILE = "oclif-command-metadata.generated.json"; export type OclifCommandMetadata = { args?: Record; baseFlags?: Record; + /** Whether the command renders public help outside oclif flag metadata. */ + customHelp?: boolean; description?: string; deprecationOptions?: unknown; examples?: string[]; @@ -83,7 +85,10 @@ function staticSummary(source: string): string | undefined { return `${brandedTemplate[1]}${CLI_DISPLAY_NAME}${brandedTemplate[2]}`; } -function staticBoolean(source: string, property: "hidden" | "strict"): boolean | undefined { +function staticBoolean( + source: string, + property: "customHelp" | "hidden" | "strict", +): boolean | undefined { const match = source.match( new RegExp(`\\bstatic\\s+(?:readonly\\s+)?${property}\\s*=\\s*(true|false)\\s*;`), ); @@ -104,9 +109,11 @@ function loadSourceOclifMetadata(commandRoot: string): Record