Add group help commands for faster agent CLI discovery (MIR-801)

[evanphx]

Summary

• Add miren help --commands to list all commands with their synopsis (supports --format json)
• Add miren help app.list version sandbox.stop to show help for multiple commands at once using dot notation
• Text output delegates to the dispatcher's ShowCommandHelp so it matches miren <cmd> -h exactly
• Bump mflags to include ShowCommandHelp export and fix for registered "help" command not being intercepted as a help keyword

Test plan

• miren help --commands shows all commands with synopsis
• miren help --commands --format json outputs JSON
• miren help app.list version shows help for both commands
• miren help app.list version --format json outputs JSON help for both
• miren help alone still shows the default help
• miren help nonexistent shows a clear error
• miren app -h still works as before
• make lint passes

[coderabbitai]

📝 Walkthrough

Walkthrough

A new global help command was added and registered with the dispatcher via RegisterAll (dispatching "help" with NewHelpCommand(d)). A new constructor func NewHelpCommand(d *mflags.Dispatcher) *Cmd and implementation were added to provide listing of commands (--commands), optional --format (table or json), and help for specific commands using dot-notation. go.mod dependency versions for golang.org/x/sys, golang.org/x/term, and miren.dev/mflags were updated.

📝 Coding Plan

• Generate coding plan for human review comments

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[phinze]

LGTM - should this get represented in the docs somehow? Maybe just as an autogen'd CLI reference page for help?

[coderabbitai]

🧹 Nitpick comments (2)

cli/commands/commands.go (1)

845-846: Comment says “registered last,” but that is not true after Line [848].

Please either move help registration below addCommands(d) or update the comment to avoid misleading future readers.

🛠️ Minimal comment-only fix

-	// Help command (registered last so it can reference all other commands)
+	// Help command (uses dispatcher state at runtime to show help for registered commands)
 	d.Dispatch("help", NewHelpCommand(d))

As per coding guidelines: "Only add comments when they provide valuable context or explain 'why' something is done - Avoid redundant comments that restate what the code does".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@cli/commands/commands.go` around lines 845 - 846, The comment claiming the
help command is "registered last" is inaccurate because addCommands(d) runs
afterwards; either move the help registration call Dispatch("help",
NewHelpCommand(d)) to after addCommands(d) so it truly is registered last, or
update the comment to remove/mcorrect the "registered last" phrasing (e.g.,
explain intended ordering or that help is registered among other commands) so
readers aren't misled.

cli/commands/help_commands.go (1)

44-55: Validate --format and reject conflicting help modes explicitly.

Line [45] currently ignores positional command names when --commands is set, and Lines [66]/[96] silently treat unknown formats as table/text. Returning explicit errors here will make CLI behavior predictable.

💡 Proposed refactor

 func (h *helpCommand) Run(fs *mflags.FlagSet, args []string) error {
+	format := strings.ToLower(strings.TrimSpace(h.format))
+	switch format {
+	case "table", "json":
+		h.format = format
+	default:
+		return fmt.Errorf("invalid --format %q (expected: table or json)", h.format)
+	}
+
+	if h.listCommands && len(h.commands) > 0 {
+		return fmt.Errorf("--commands cannot be combined with command names")
+	}
+
 	if h.listCommands {
 		return h.runListCommands()
 	}

Also applies to: 63-71, 95-103

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@cli/commands/help_commands.go` around lines 44 - 55, The Run method on
helpCommand currently allows conflicting modes and silently accepts unknown
--format values; update helpCommand.Run to explicitly validate conflicts and
formats: if h.listCommands && len(h.commands) > 0 return an error indicating
--commands conflicts with positional command names, and validate h.format
against the allowed set (e.g. "table","text","json") before dispatching to
runListCommands or runMultiHelp; on unknown format return an explicit error
instead of falling back. Ensure the checks occur at the top of helpCommand.Run
(before calling runListCommands or runMultiHelp) and include clear error
messages referencing the --format flag and the conflicting modes.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@cli/commands/commands.go`:
- Around line 845-846: The comment claiming the help command is "registered
last" is inaccurate because addCommands(d) runs afterwards; either move the help
registration call Dispatch("help", NewHelpCommand(d)) to after addCommands(d) so
it truly is registered last, or update the comment to remove/mcorrect the
"registered last" phrasing (e.g., explain intended ordering or that help is
registered among other commands) so readers aren't misled.

In `@cli/commands/help_commands.go`:
- Around line 44-55: The Run method on helpCommand currently allows conflicting
modes and silently accepts unknown --format values; update helpCommand.Run to
explicitly validate conflicts and formats: if h.listCommands && len(h.commands)
> 0 return an error indicating --commands conflicts with positional command
names, and validate h.format against the allowed set (e.g.
"table","text","json") before dispatching to runListCommands or runMultiHelp; on
unknown format return an explicit error instead of falling back. Ensure the
checks occur at the top of helpCommand.Run (before calling runListCommands or
runMultiHelp) and include clear error messages referencing the --format flag and
the conflicting modes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 511c22f6-d203-4149-938e-4342bb26b890

📥 Commits

Reviewing files that changed from the base of the PR and between 765443a and 3f5257a.

⛔ Files ignored due to path filters (1)

• go.sum is excluded by !**/*.sum

📒 Files selected for processing (3)

• cli/commands/commands.go
• cli/commands/help_commands.go
• go.mod

[evanphx]

@phinze it will be include on all miren.md automatically if that's what you mean?

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

cli/commands/help_commands.go (1)

90-102: Extract command-path normalization to a helper to avoid drift.

Line 90 and Line 101 duplicate dot-notation normalization. A tiny helper keeps JSON/text paths consistent if behavior changes later.

Refactor sketch

+func normalizeHelpPath(name string) string {
+	return strings.ReplaceAll(name, ".", " ")
+}
+
 func runMultiHelp(d *mflags.Dispatcher, opts helpOpts) error {
@@
-			path := strings.ReplaceAll(name, ".", " ")
+			path := normalizeHelpPath(name)
@@
-		path := strings.ReplaceAll(name, ".", " ")
+		path := normalizeHelpPath(name)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@cli/commands/help_commands.go` around lines 90 - 102, The code duplicates
dot-to-space normalization (strings.ReplaceAll(name, ".", " ")) in
help_commands.go; extract this into a single helper (e.g.,
normalizeCommandPath(name string) string or commandPathFromName) and replace
both occurrences where path is assigned (the two places using
strings.ReplaceAll) with calls to that helper so command-path normalization is
centralized and consistent for both JSON and text paths (leave PrintJSON/results
logic unchanged).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@cli/commands/help_commands.go`:
- Around line 28-33: The current logic lets opts.ListCommands silently override
positional command names (opts.Commands) by calling runListCommands when both
are present; add an explicit conflict check before the existing branches: if
opts.ListCommands && len(opts.Commands) > 0 then return a usage/error indicating
the flags are mutually exclusive (so callers get a clear message) instead of
falling through to runListCommands or runMultiHelp; update the handler that
currently calls runListCommands and runMultiHelp to perform this check and
return an error (or proper usage output) when the conflict is detected.

---

Nitpick comments:
In `@cli/commands/help_commands.go`:
- Around line 90-102: The code duplicates dot-to-space normalization
(strings.ReplaceAll(name, ".", " ")) in help_commands.go; extract this into a
single helper (e.g., normalizeCommandPath(name string) string or
commandPathFromName) and replace both occurrences where path is assigned (the
two places using strings.ReplaceAll) with calls to that helper so command-path
normalization is centralized and consistent for both JSON and text paths (leave
PrintJSON/results logic unchanged).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a43817c7-76b6-45e9-844b-7d7a57fd7408

📥 Commits

Reviewing files that changed from the base of the PR and between 3f5257a and 8c794aa.

⛔ Files ignored due to path filters (1)

• go.sum is excluded by !**/*.sum

📒 Files selected for processing (3)

• cli/commands/commands.go
• cli/commands/help_commands.go
• go.mod

🚧 Files skipped from review as they are similar to previous changes (2)

• go.mod
• cli/commands/commands.go