feat: organize CLI help commands into logical groups

[ralphbean]

Summary

As a new user, I felt overwhelmed by the variety of subcommands. Lots of check* options mixed in with audit and verify. At a certain level, "check" and "verify" feel like synonyms. The --help didn't help me build a mental model for how the subcommands should be used in a workflow.

In this change, I organized the sourcetool CLI help output into four logical command groups to hopefully improve comprehension and user experience.

Changes

Command Groups

Verification Commands (2 commands)

• audit - Verifies multiple commits in the branch history
• verifycommit - Verifies the specified commit is valid

Assessment Commands (5 commands)

• status - Check the SLSA Source status of a repo/branch
• checklevel - Determines the SLSA Source Level of the repo
• checklevelprov - Checks the given commit against policy using & creating provenance
• checktag - Checks to see if the tag operation should be allowed and issues a VSA
• prov - Creates provenance for the given commit, but does not check policy

Policy Commands (2 commands)

• policy - tools to work with source policies
• createpolicy - Creates a policy in a local copy of source-policies

Configuration & Setup Commands (2 commands)

• auth - Manage user authentication
• setup - configure SLSA source features in a repository

Implementation Details

• Uses Cobra's AddGroup feature (supported in v1.10.1+)
• Each command is assigned a GroupID to categorize it
• "Assessment" encompasses both evaluation and attestation creation
• "Verification" is reserved for commands that verify existing attestations

Rationale

Why move status to Assessment?

• status reads GitHub API controls, not VSAs (same data sources as checklevel)
• Functionally similar to checklevel - both evaluate controls to determine SLSA level
• status is essentially a read-only version of checklevel
• Makes "Verification" group more cohesive (only commands that verify existing attestations)

Why "Assessment" instead of "Evaluation"?

• Broad enough to cover both evaluation and attestation creation
• 4 of 5 commands evaluate policy
• 4 of 5 commands create attestations
• "Assessment" encompasses both aspects

Testing

• ✅ All unit tests pass
• ✅ golangci-lint clean (0 issues)
• ✅ Help output verified manually

Before/After

Before:

Available Commands:
  audit          Audits the SLSA properties and controls of a repository
  auth           Manage user authentication
  checklevel     Determines the SLSA Source Level of the repo
  checklevelprov Checks the given commit against policy using & creating provenance
  checktag       Checks to see if the tag operation should be allowed and issues a VSA
  completion     Generate the autocompletion script for the specified shell
  createpolicy   Creates a policy in a local copy of source-policies
  help           Help about any command
  policy         tools to work with source policies
  prov           Creates provenance for the given commit, but does not check policy.
  setup          configure SLSA source features in a repository
  status         Check the SLSA Source status of a repo/branch
  verifycommit   Verifies the specified commit is valid

After:

Verification Commands:
  audit          Verifies multiple commits in the branch history
  verifycommit   Verifies the specified commit is valid

Assessment Commands:
  checklevel     Determines the SLSA Source Level of the repo
  checklevelprov Checks the given commit against policy using & creating provenance
  checktag       Checks to see if the tag operation should be allowed and issues a VSA
  prov           Creates provenance for the given commit, but does not check policy.
  status         Check the SLSA Source status of a repo/branch

Policy Commands:
  createpolicy   Creates a policy in a local copy of source-policies
  policy         tools to work with source policies

Configuration & Setup Commands:
  auth           Manage user authentication
  setup          configure SLSA source features in a repository

---

Generated with assistance from Claude Code

[TomHennen]

Thanks, this generally LGTM. I definitely understand the confusion around the many commands, most of that is my fault. I think @puerco has plans to eventually remove some of the redundant ones.

Does this look good to you Puerco?

[puerco]

I love how much clearer the CLI is now @ralphbean !

Even if we consolidate some of the commands later, the groups describe well the current and planned functions of the tool, so any upcoming features will fit within them. Thanks!