Enforce bare-group-shows-help convention

[jeremy]

Summary

Command groups (resource nouns with subcommands like todos, projects, todosets) should show help when invoked bare — not run a default action. This was an unwritten convention that #270 nearly violated. Now it's codified three ways:

• Style guide: STYLE.md documents the rule and the shortcut exception
• CI check: scripts/check-bare-groups.sh scans Go source for NewXxxCmd functions with both RunE and AddCommand, failing unless the function is in an explicit allowlist of intentional shortcuts (card, search, url, etc.)
• E2e coverage: added "without subcommand shows help" tests for 8 command groups that were missing them

Also removes redundant RunE: cmd.Help() from boost, mcp, and tools — Cobra already shows help by default when a parent command has subcommands.

Test plan

• bin/ci passes — new check-bare-groups target runs green
• All 8 new e2e bare-help tests pass
• Verified the check catches violations (tested by temporarily adding RunE to a group command)

---

Summary by cubic

Enforces that bare command groups show help instead of running an action. Adds a CI check, updates the style guide, expands e2e coverage, removes redundant handlers, and acknowledges the mcp CLI surface change.

• New Features

  • Documented the rule in STYLE.md with an allowlist for shortcut commands (card, search, url, etc.).
  • Added scripts/check-bare-groups.sh and wired it into make check as check-bare-groups to block RunE + AddCommand on group parents.
  • Added “without subcommand shows help” e2e tests for auth, boost, campfire, files, messagetypes, subscriptions, templates, and webhooks.

• Refactors

  • Removed redundant RunE: cmd.Help() from boost, mcp, and tools (rely on Cobra’s default help).
  • Added .surface-breaking entries for mcp to acknowledge the CLI surface change from removing RunE.

^{Written for commit fc22351. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 14 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/check-bare-groups.sh">

<violation number="1" location="scripts/check-bare-groups.sh:43">
P1: Non-portable BRE alternation (`\|`) silently breaks the check on macOS. BSD grep doesn't support `\|` in basic regex, so the pattern matches nothing and the script always passes — defeating its purpose for developers running `bin/ci` locally on macOS. Use `-Ec` with `|` instead.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[Copilot]

Pull request overview

Codifies the CLI convention that “group” commands (resource nouns with subcommands) should show help when invoked without a subcommand, rather than running a default action.

Changes:

• Document the bare-group-shows-help rule (and shortcut exceptions) in STYLE.md.
• Add a CI-enforced checker script and wire it into the make check pipeline.
• Add e2e tests ensuring bare invocation shows help for several command groups; remove redundant RunE: cmd.Help() from a few commands.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
scripts/check-bare-groups.sh	Adds a CI check to detect New*Cmd constructors that set both RunE and AddCommand unless allowlisted.
internal/commands/tools.go	Removes redundant parent RunE that only printed help.
internal/commands/mcp.go	Removes redundant parent RunE that only printed help.
internal/commands/boost.go	Removes redundant parent RunE (and no-op Args) so bare invocation relies on Cobra help behavior.
e2e/webhooks.bats	Adds “without subcommand shows help” coverage.
e2e/templates.bats	Adds “without subcommand shows help” coverage.
e2e/subscriptions.bats	Adds “without subcommand shows help” coverage.
e2e/messagetypes.bats	Adds “without subcommand shows help” coverage.
e2e/files.bats	Adds “without subcommand shows help” coverage.
e2e/campfire.bats	Adds “without subcommand shows help” coverage.
e2e/boost.bats	Adds “without subcommand shows help” coverage.
e2e/auth.bats	Adds “without subcommand shows help” coverage.
STYLE.md	Documents the bare-group-shows-help convention and the shortcut exception.
Makefile	Adds check-bare-groups target and includes it in check.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.