feat: organize CLI help commands into logical groups (#317)

* feat: organize help commands into logical groups

Organize the sourcetool CLI help output into three logical command
groups to improve discoverability and user experience:

- Verification Commands: verifycommit, audit, status
- Attestation & Evaluation Commands: checklevel, checklevelprov,
  checktag, prov
- Configuration & Setup Commands: setup, auth, policy, createpolicy

This uses Cobra's AddGroup feature to categorize commands by their
primary function, making it easier for users to find the command
they need.

Assisted-by: Claude Code
Signed-off-by: Ralph Bean <[email protected]>

* refactor: separate policy commands into dedicated group

Move createpolicy and policy commands from the Configuration & Setup
group into their own Policy Commands group for better organization.

The help output now shows four distinct command groups:
- Verification Commands
- Attestation & Evaluation Commands
- Policy Commands
- Configuration & Setup Commands

This makes policy management commands more discoverable and logically
separated from general configuration tasks.

Assisted-by: Claude Code
Signed-off-by: Ralph Bean <[email protected]>

* docs: clarify audit command description

Change audit command short description from "Audits the SLSA properties
and controls of a repository" to "Verifies multiple commits in the branch
history" to better describe what the command actually does.

The word "multiple" is more accurate than "all" since the command can be
limited with --depth and --ending-commit flags.

Assisted-by: Claude Code
Signed-off-by: Ralph Bean <[email protected]>

* refactor: reorganize commands into Assessment group

Rename "Attestation & Evaluation Commands" to "Assessment Commands"
and move status from Verification to Assessment group.

The new organization better reflects command behavior:

Verification Commands (2):
- audit: verifies multiple commits by reading existing VSAs
- verifycommit: verifies single commit by reading existing VSA

Assessment Commands (5):
- status: assesses current repository controls
- checklevel: assesses controls and creates VSA
- checklevelprov: assesses with provenance creation
- checktag: assesses tag operations
- prov: creates provenance without policy evaluation

"Assessment" encompasses both evaluation (status, checklevel) and
attestation creation (prov), making it a better umbrella term than
"Attestation & Evaluation".

Assisted-by: Claude Code
Signed-off-by: Ralph Bean <[email protected]>

---------

Signed-off-by: Ralph Bean <[email protected]>

Author: ralphbean

internal/cmd/audit.go

@@ -81,8 +81,9 @@ func (ao *auditOpts) AddFlags(cmd *cobra.Command) {
 func addAudit(parentCmd *cobra.Command) {
 	opts := &auditOpts{}
 	auditCmd := &cobra.Command{
-		Use:   "audit",
-		Short: "Audits the SLSA properties and controls of a repository",
+		Use:     "audit",
+		GroupID: "verification",
+		Short:   "Verifies multiple commits in the branch history",
 		Long: `Checks the revisions on the specified branch within the repository.
 
 Revisions 'pass' an audit if they have:

internal/cmd/auth.go

@@ -18,6 +18,7 @@ var colorHiRed = color.New(color.FgHiRed).SprintFunc()
 
 func addAuth(parentCmd *cobra.Command) {
 	authCmd := &cobra.Command{
+		GroupID:       "configuration",
 		Short:         "Manage user authentication",
 		Use:           "auth",
 		SilenceUsage:  false,

internal/cmd/checklevel.go

@@ -42,8 +42,9 @@ func addCheckLevel(parentCmd *cobra.Command) {
 	opts := checkLevelOpts{}
 
 	checklevelCmd := &cobra.Command{
-		Use:   "checklevel",
-		Short: "Determines the SLSA Source Level of the repo",
+		Use:     "checklevel",
+		GroupID: "assessment",
+		Short:   "Determines the SLSA Source Level of the repo",
 		Long: `Determines the SLSA Source Level of the repo.
 
 This is meant to be run within the corresponding GitHub Actions workflow.`,

internal/cmd/checklevelprov.go

@@ -51,8 +51,9 @@ func addCheckLevelProv(parentCmd *cobra.Command) {
 	opts := &checkLevelProvOpts{}
 
 	checklevelprovCmd := &cobra.Command{
-		Use:   "checklevelprov",
-		Short: "Checks the given commit against policy using & creating provenance",
+		Use:     "checklevelprov",
+		GroupID: "assessment",
+		Short:   "Checks the given commit against policy using & creating provenance",
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			if len(args) > 0 {
 				if err := opts.ParseLocator(args[0]); err != nil {

internal/cmd/checktag.go

@@ -50,8 +50,9 @@ func addCheckTag(parentCmd *cobra.Command) {
 	opts := &checkTagOptions{}
 
 	checktagCmd := &cobra.Command{
-		Use:   "checktag",
-		Short: "Checks to see if the tag operation should be allowed and issues a VSA",
+		Use:     "checktag",
+		GroupID: "assessment",
+		Short:   "Checks to see if the tag operation should be allowed and issues a VSA",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return doCheckTag(opts)
 		},

internal/cmd/createpolicy.go

@@ -30,8 +30,9 @@ func addCreatePolicy(parentCmd *cobra.Command) {
 	opts := createPolicyOptions{}
 
 	createpolicyCmd := &cobra.Command{
-		Use:   "createpolicy",
-		Short: "Creates a policy in a local copy of source-policies",
+		Use:     "createpolicy",
+		GroupID: "policy",
+		Short:   "Creates a policy in a local copy of source-policies",
 		Long: `Creates a SLSA source policy in a local copy of source-policies.
 
 		The created policy should then be sent as a PR to slsa-framework/source-policies.`,

internal/cmd/policy.go

@@ -39,7 +39,8 @@ func (pco *policyCreateOpts) AddFlags(cmd *cobra.Command) {
 
 func addPolicy(parentCmd *cobra.Command) {
 	policyCmd := &cobra.Command{
-		Short: "tools to work with source policies",
+		GroupID: "policy",
+		Short:   "tools to work with source policies",
 		Long: fmt.Sprintf(`
 %s %s
 

internal/cmd/prov.go

@@ -40,8 +40,9 @@ func (po *provOptions) AddFlags(cmd *cobra.Command) {
 func addProv(parentCmd *cobra.Command) {
 	opts := provOptions{}
 	provCmd := &cobra.Command{
-		Use:   "prov",
-		Short: "Creates provenance for the given commit, but does not check policy.",
+		Use:     "prov",
+		GroupID: "assessment",
+		Short:   "Creates provenance for the given commit, but does not check policy.",
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			if len(args) > 0 {
 				if err := opts.ParseLocator(args[0]); err != nil {

internal/cmd/root.go

@@ -44,17 +44,45 @@ controls and much more.
 
 	rootCmd.PersistentFlags().StringVar(&githubToken, "github_token", "", "the github token to use for auth")
 
-	addCheckLevel(rootCmd)
-	addCheckLevelProv(rootCmd)
+	// Define command groups for better organization
+	rootCmd.AddGroup(
+		&cobra.Group{
+			ID:    "verification",
+			Title: "Verification Commands:",
+		},
+		&cobra.Group{
+			ID:    "assessment",
+			Title: "Assessment Commands:",
+		},
+		&cobra.Group{
+			ID:    "policy",
+			Title: "Policy Commands:",
+		},
+		&cobra.Group{
+			ID:    "configuration",
+			Title: "Configuration & Setup Commands:",
+		},
+	)
+
+	// Verification commands
 	addVerifyCommit(rootCmd)
-	addStatus(rootCmd)
-	addSetup(rootCmd)
 	addAudit(rootCmd)
-	addProv(rootCmd)
+
+	// Assessment commands
+	addStatus(rootCmd)
+	addCheckLevel(rootCmd)
+	addCheckLevelProv(rootCmd)
 	addCheckTag(rootCmd)
+	addProv(rootCmd)
+
+	// Policy commands
+	addPolicy(rootCmd)
 	addCreatePolicy(rootCmd)
+
+	// Configuration & setup commands
+	addSetup(rootCmd)
 	addAuth(rootCmd)
-	addPolicy(rootCmd)
+
 	return rootCmd
 }
 

internal/cmd/setup.go

@@ -52,7 +52,8 @@ func (so *setupOpts) Validate() error {
 
 func addSetup(parentCmd *cobra.Command) {
 	setupCmd := &cobra.Command{
-		Short: "configure SLSA source features in a repository",
+		GroupID: "configuration",
+		Short:   "configure SLSA source features in a repository",
 		Long: fmt.Sprintf(`
 %s %s