BREAKING CHANGE(cliutils): ensure lazy help rendering (#15)

For ordinary commands, help rendering seems already lazy because we
explicitly need to invoke the Help method.

Conversely, for NewCommandWithSubCommands the help is passed as a
string, which means markdown rendering happens unconditionally.

This has negative implications including generation of garbled output
including terminal escape sequences when we put a process in background
using the shell.

To fix, make help rendering lazy also for NewCommandWithSubCommands.

cliutils/cliutils_test.go

@@ -75,7 +75,7 @@ func TestCommandWithSubCommands(t *testing.T) {
 	for _, tc := range cases {
 		t.Run(strings.Join(tc.argv, " "), func(t *testing.T) {
 			cmd := cliutils.NewCommandWithSubCommands(
-				"rbmk", "", map[string]cliutils.Command{
+				"rbmk", cliutils.LazyHelpRendererFunc(func() string { return "" }), map[string]cliutils.Command{
 					"env": fakecmd{},
 				},
 			)

cliutils/clutils.go

@@ -71,25 +71,42 @@ type CommandWithSubCommands struct {
 	// commands is the map of subcommands.
 	commands map[string]Command
 
-	// help is the help string.
-	help string
-
 	// name is the full name of this command.
 	name string
+
+	// renderer is the help renderer.
+	renderer LazyHelpRenderer
+}
+
+// LazyHelpRenderer renders the help possibly adding colours and formatting.
+type LazyHelpRenderer interface {
+	Help() string
+}
+
+// LazyHelpRendererFunc is a function that implements [LazyHelpRenderer].
+type LazyHelpRendererFunc func() string
+
+// Ensure that [LazyHelpRendererFunc] implements [LazyHelpRenderer].
+var _ LazyHelpRenderer = LazyHelpRendererFunc(nil)
+
+// Help implements HelpRenderer.
+func (fx LazyHelpRendererFunc) Help() string {
+	return fx()
 }
 
 // NewCommandWithSubCommands constructs a [CommandWithSubCommands].
 //
 // The name argument contains the full name of this command (e.g., `rbmk run`).
 //
-// The help argument contains the help string.
+// The renderer argument renders the help on demand.
 //
 // The commands argument contains the implemented subcommands.
-func NewCommandWithSubCommands(name string, help string, commands map[string]Command) CommandWithSubCommands {
+func NewCommandWithSubCommands(name string,
+	renderer LazyHelpRenderer, commands map[string]Command) CommandWithSubCommands {
 	return CommandWithSubCommands{
 		commands: commands,
-		help:     help,
 		name:     name,
+		renderer: renderer,
 	}
 }
 
@@ -99,7 +116,7 @@ var _ Command = CommandWithSubCommands{}
 func (c CommandWithSubCommands) Help(env Environment, argv ...string) error {
 	// 1. case where we're invoked with no arguments
 	if len(argv) < 2 {
-		fmt.Fprintf(env.Stderr(), "%s\n", c.help)
+		fmt.Fprintf(env.Stderr(), "%s\n", c.renderer.Help())
 		return nil
 	}