From 482018e536438ec8d60fc371725336790755fb36 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 27 May 2026 02:49:40 -0400
Subject: [PATCH] fix: mark plugin command groups in root help

---
 src/cli/program/help.ts           | 13 +++++++++++--
 src/cli/program/root-help.test.ts |  1 +
 src/cli/program/root-help.ts      | 23 ++++++++++++++++-------
 3 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/src/cli/program/help.ts b/src/cli/program/help.ts
index b08a0372ac5..56f7673283c 100644
--- a/src/cli/program/help.ts
+++ b/src/cli/program/help.ts
@@ -43,7 +43,16 @@ const EXAMPLES = [
   ],
 ] as const;
 
-export function configureProgramHelp(program: Command, ctx: ProgramContext) {
+export function configureProgramHelp(
+  program: Command,
+  ctx: ProgramContext,
+  options?: { commandsWithSubcommands?: ReadonlySet<string> },
+) {
+  const commandsWithSubcommands = new Set([
+    ...ROOT_COMMANDS_WITH_SUBCOMMANDS,
+    ...(options?.commandsWithSubcommands ?? []),
+  ]);
+
   program
     .name(CLI_NAME)
     .description("")
@@ -77,7 +86,7 @@ export function configureProgramHelp(program: Command, ctx: ProgramContext) {
     optionTerm: (option) => theme.option(option.flags),
     subcommandTerm: (cmd) => {
       const isRootCommand = cmd.parent === program;
-      const hasSubcommands = isRootCommand && ROOT_COMMANDS_WITH_SUBCOMMANDS.has(cmd.name());
+      const hasSubcommands = isRootCommand && commandsWithSubcommands.has(cmd.name());
       return theme.command(hasSubcommands ? `${cmd.name()} *` : cmd.name());
     },
   });
diff --git a/src/cli/program/root-help.test.ts b/src/cli/program/root-help.test.ts
index c7149867e49..e5f77eddddc 100644
--- a/src/cli/program/root-help.test.ts
+++ b/src/cli/program/root-help.test.ts
@@ -80,6 +80,7 @@ describe("root help", () => {
     expect(text).toContain("status");
     expect(text).toContain("config");
     expect(text).toContain("matrix");
+    expect(text).toContain("matrix *");
     expect(text).toContain("Matrix channel utilities");
   });
 
diff --git a/src/cli/program/root-help.ts b/src/cli/program/root-help.ts
index 2b1962ce191..dc6d230f104 100644
--- a/src/cli/program/root-help.ts
+++ b/src/cli/program/root-help.ts
@@ -19,19 +19,28 @@ export type RootHelpRenderOptions = Pick<PluginLoadOptions, "pluginSdkResolution
 
 async function buildRootHelpProgram(renderOptions?: RootHelpRenderOptions): Promise<Command> {
   const program = new Command();
-  configureProgramHelp(program, {
-    programVersion: VERSION,
-    channelOptions: [],
-    messageChannelOptions: "",
-    agentChannelOptions: "",
-  });
-
   const pluginDescriptors =
     renderOptions?.includePluginDescriptors === true || renderOptions?.config
       ? await getPluginCliCommandDescriptors(renderOptions.config, renderOptions.env, {
           pluginSdkResolution: renderOptions.pluginSdkResolution,
         })
       : [];
+  configureProgramHelp(
+    program,
+    {
+      programVersion: VERSION,
+      channelOptions: [],
+      messageChannelOptions: "",
+      agentChannelOptions: "",
+    },
+    {
+      commandsWithSubcommands: new Set(
+        pluginDescriptors
+          .filter((descriptor) => descriptor.hasSubcommands)
+          .map((descriptor) => descriptor.name),
+      ),
+    },
+  );
 
   addCommandDescriptorsToProgram(
     program,