stackrox · parametalol · Mar 10, 2025 · Feb 21, 2025 · Feb 21, 2025 · Feb 21, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@ Please avoid adding duplicate information across this changelog and JIRA/doc inp
 ## [NEXT RELEASE]
 
 ### Added Features
+
 - ROX-13493: Support for scale subresource in the admission controller to enable policy detection and enforcement on admission review requests on the scale subresource.
 
 ### Removed Features
@@ -18,9 +19,9 @@ Please avoid adding duplicate information across this changelog and JIRA/doc inp
 
 ### Technical Changes
 
-## [4.7.0]
-
+- ROX-28263: New `roxctl` help formatting.
 
+## [4.7.0]
 
 ### Added Features
 

@@ -7,8 +7,7 @@ import (
 )
 
 const (
-	warningDeprecatedDbBackup = `WARNING: The backup command has been deprecated. Please use "roxctl central backup"
-to create central backup with database, keys and certificates.`
+	warningDeprecatedDbBackup = `Please use "roxctl central backup" to create central backup with database, keys and certificates.`
 )
 
 // Command defines the db backup command. This command is deprecated and can be removed on or after 3.0.57.

@@ -69,7 +69,7 @@
 
 	c.Flags().StringVar(&centralDbRestoreCmd.file, "file", "", "File to restore the DB from (deprecated; use positional argument)")
 	c.Flags().BoolVar(&centralDbRestoreCmd.interrupt, "interrupt", false, "Interrupt ongoing restore process (if any) to allow resuming")
-	utils.Must(c.Flags().MarkDeprecated("file", "--file is deprecated; use the positional argument instead"))
+	utils.Must(c.Flags().MarkDeprecated("file", "use the positional argument instead"))
 	flags.AddForce(c)
 
 	return c

@@ -9,6 +9,7 @@
 	"github.com/stackrox/rox/pkg/sync"
 	"github.com/stackrox/rox/roxctl/common"
 	"github.com/stackrox/rox/roxctl/maincommand"
+	"github.com/stackrox/rox/roxctl/utils"
 
 	// Make sure devbuild setting is registered.
 	_ "github.com/stackrox/rox/pkg/devbuild"
@@ -17,18 +18,7 @@
 func main() {
 	c := maincommand.Command()
 
-	// This is a workaround. Cobra/pflag takes care of presenting flag usage information
-	// to the user including the respective flag default values.
-	//
-	// But, as an exception, showing the default value for a flag is skipped in pflag if
-	// that value is the zero value for a certain standard type.
-	//
-	// In our case this caused the unintended behaviour of not showing the default values
-	// for our boolean flags which default to `false`.
-	//
-	// Until we have a better solution (e.g. way to control this behaviour in upstream pflag)
-	// we simply add the usage information "(default false)" to our affected boolean flags.
-	AddMissingDefaultsToFlagUsage(c)
+	c.SetHelpFunc(utils.FormatHelp)
 
 	once := sync.Once{}
 	// Peak only the deepest command path. The hooks are added to all commands.

@@ -26,7 +26,6 @@ func mockRunE(_ *cobra.Command, _ []string) error { return nil }
 
 func TestCommandReconstruction(t *testing.T) {
 	root := maincommand.Command()
-	AddMissingDefaultsToFlagUsage(root)
 
 	type testCase struct {
 		args    []string

@@ -53,6 +53,8 @@ func versionCommand(cliEnvironment environment.Environment) *cobra.Command {
 // Command constructs and returns the roxctl command tree
 func Command() *cobra.Command {
 	c := &cobra.Command{
+		Long: "roxctl is a command-line interface (CLI) for running commands" +
+			" on Red Hat Advanced Cluster Security for Kubernetes (RHACS)",
 		SilenceUsage: true,
 		Use:          os.Args[0],
 	}

@@ -36,7 +36,7 @@ func checkUsageFirstCharacter(t *testing.T, command *cobra.Command) {
 	if !isCapitalized(command.Short) {
 		t.Errorf("%q, short usage: %q", getCommandPath(command), command.Short)
 	}
-	if !isCapitalized(command.Long) {
+	if !isCapitalized(command.Long) && !strings.HasPrefix(command.Long, "roxctl ") {
 		t.Errorf("%q, long usage: %q", getCommandPath(command), command.Long)
 	}
 	for _, subcommand := range command.Commands() {

@@ -0,0 +1,116 @@
+package utils
+
+import (
+	"bufio"
+	"io"
+	"strings"
+)
+
+const defaultTabWidth = 8
+
+// formattingWriter implements StringWriter interface.
+// It writes strings to the underlying writer indenting and wrapping the text.
+type formattingWriter struct {
+	raw      io.StringWriter
+	width    int
+	indent   indents
+	tabWidth int
+
+	currentLine int
+	written     int
+	indentReset bool
+}
+
+var _ io.StringWriter = (*formattingWriter)(nil)
+
+func makeFormattingWriter(w io.StringWriter, width int, tabWidth int, indent ...int) *formattingWriter {
+	return &formattingWriter{raw: w, width: width, indent: indent, tabWidth: tabWidth}
+}
+
+// write is an internal method that writes the string to the underlying writer.
+func (w *formattingWriter) write(s string) error {
+	n, err := w.raw.WriteString(s)
+	w.currentLine += n
+	w.written += n
+	return err //nolint:wrapcheck
+}
+
+// writePadding is an internal method, that takes the next indent value and the
+// writes the according number of spaces. If the indent value is negative, it is
+// calculated as tabulation offset, i.e. the spaces are added to reach the
+// required offset. Returns true if a new line has been written.
+func (w *formattingWriter) writePadding() (bool, error) {
+	w.indentReset = false
+	padding := w.indent.popNotLast()
+	if padding < 0 {
+		// Indent to tabulation.
+		padding = -padding
+		if padding > w.currentLine {
+			padding -= w.currentLine
+		} else {
+			return true, nil
+		}
+	} else if w.currentLine+padding > w.width {
+		return true, nil
+	}
+	return false, w.write(strings.Repeat(" ", padding))
+}
+
+// ln is an internal method that writes a new line to the underlying writer.
+func (w *formattingWriter) ln() error {
+	_, err := w.raw.WriteString("\n")
+	w.currentLine = 0
+	return err //nolint:wrapcheck
+}
+
+// SetIndent updates the indentation for the following writings.
+func (w *formattingWriter) SetIndent(indent ...int) {
+	w.indentReset = true
+	w.indent = indent
+}
+
+// WriteString writes the string to the underlying writer, with the configured
+// indentation and wrapping.
+// Implements the StringWriter interface.
+func (w *formattingWriter) WriteString(s string) (int, error) {
+	w.written = 0
+	tokenScanner := bufio.NewScanner(strings.NewReader(s))
+	tokenScanner.Split(wordsAndDelimeters)
+	var err error
+	for err == nil && tokenScanner.Scan() {
+		token := tokenScanner.Text()
+		length := len(token)
+		switch token {
+		case "\t":
+			length = defaultTabWidth
+		case "\n":
+			if w.currentLine == 0 {
+				w.indent.popNotLast()
+				w.indentReset = false
+			}
+			err = w.ln()
+			continue
+		}
+		ln := false
+		if w.currentLine == 0 || w.indentReset {
+			if ln, err = w.writePadding(); err != nil {
+				break
+			}
+		}
+		// Write a new line and a padding in case of line overflow:
+		if ln || w.currentLine+length > w.width {
+			if err = w.ln(); err != nil {
+				break
+			}
+			if token == " " {
+				// Do not write space token that caused line break.
+				continue
+			}
+			if _, err = w.writePadding(); err != nil {
+				break
+			}
+		}
+		err = w.write(token)
+	}
+	return w.written, err
+}