cobra: fix test failures, add Examples/AddGroup, improve comments

[Copilot]

The TestRegisterFlagCompletions tests were failing because MarkFlagFilename/MarkFlagDirname (already adopted) use flag annotations rather than RegisterFlagCompletionFunc, so GetFlagCompletionFunc returned nothing. This PR fixes those tests and completes the remaining cobra improvement items from the Go Fan report.

Changes

Bug fix: test assertions for annotation-based completions (flags_test.go)

• Replaced GetFlagCompletionFunc checks with direct annotation checks (BashCompFilenameExt / BashCompSubdirsInDir) for config, log-dir, payload-dir, and env flags

Help output improvements (root.go, proxy.go)

• Added Example field to rootCmd and proxy command — gives the dedicated "Examples:" section in --help output
• Added AddGroup in rootCmd.init() with "Operation Modes:" and "Utilities:" groups; assigned GroupID to proxy (modes) and completion (utils)

Comments (proxy.go, completion.go)

• Documented why --listen / --log-dir are re-declared on proxy rather than inherited as persistent flags (different defaults, distinct runtime purpose)
• Expanded the PersistentPreRunE override comment to explain cobra does not chain PersistentPreRunE hooks automatically — child's hook fully replaces the parent's

Test helpers (completion_test.go)

• newTestRootWithCompletion() and TestNewCompletionCmd_OverridesParentPersistentPreRunE now call AddGroup for "utils" so the GroupID on the completion command doesn't panic when Execute() is called in isolation

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• example.com
  • Triggering command: /tmp/go-build2287418252/b509/launcher.test /tmp/go-build2287418252/b509/launcher.test -test.testlogfile=/tmp/go-build2287418252/b509/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true 2/compile.go 2/equals.go x_amd64/compile (dns block)
  • Triggering command: /tmp/go-build299607628/b513/launcher.test /tmp/go-build299607628/b513/launcher.test -test.testlogfile=/tmp/go-build299607628/b513/testlog.txt -test.paniconexit0 -test.timeout=10m0s /tmp/go-build299607628/b500/vet.cfg g_.a -trimpath x_amd64/link -p google.golang.or/tmp/go-build556243166/b360/vet.cfg -lang=go1.24 x_amd64/link -ato�� khb6c8mIR -buildtags x_amd64/vet -errorsas -ifaceassert -nilfunc x_amd64/vet (dns block)
• invalid-host-that-does-not-exist-12345.com
  • Triggering command: /tmp/go-build2287418252/b491/config.test /tmp/go-build2287418252/b491/config.test -test.testlogfile=/tmp/go-build2287418252/b491/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true ktype/networktype.go 64/src/encoding/google.golang.org/grpc/internal x_amd64/compile (dns block)
  • Triggering command: /tmp/go-build299607628/b495/config.test /tmp/go-build299607628/b495/config.test -test.testlogfile=/tmp/go-build299607628/b495/testlog.txt -test.paniconexit0 -test.timeout=10m0s -o pkg/mod/google.golang.org/protobuf@v1.36.11/type-s -trimpath 64/pkg/tool/linux_amd64/vet -p google.golang.or/tmp/go-build556243166/b288/vet.cfg -lang=go1.23 64/pkg/tool/linux_amd64/vet -o /tmp/go-build2287418252/b434/_pk--log-target -trimpath 64/bin/go -p google.golang.or/tmp/go-build556243166/b396/vet.cfg -lang=go1.24 ker/cli-plugins/docker-compose (dns block)
• nonexistent.local
  • Triggering command: /tmp/go-build2287418252/b509/launcher.test /tmp/go-build2287418252/b509/launcher.test -test.testlogfile=/tmp/go-build2287418252/b509/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true 2/compile.go 2/equals.go x_amd64/compile (dns block)
  • Triggering command: /tmp/go-build299607628/b513/launcher.test /tmp/go-build299607628/b513/launcher.test -test.testlogfile=/tmp/go-build299607628/b513/testlog.txt -test.paniconexit0 -test.timeout=10m0s /tmp/go-build299607628/b500/vet.cfg g_.a -trimpath x_amd64/link -p google.golang.or/tmp/go-build556243166/b360/vet.cfg -lang=go1.24 x_amd64/link -ato�� khb6c8mIR -buildtags x_amd64/vet -errorsas -ifaceassert -nilfunc x_amd64/vet (dns block)
• slow.example.com
  • Triggering command: /tmp/go-build2287418252/b509/launcher.test /tmp/go-build2287418252/b509/launcher.test -test.testlogfile=/tmp/go-build2287418252/b509/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true 2/compile.go 2/equals.go x_amd64/compile (dns block)
  • Triggering command: /tmp/go-build299607628/b513/launcher.test /tmp/go-build299607628/b513/launcher.test -test.testlogfile=/tmp/go-build299607628/b513/testlog.txt -test.paniconexit0 -test.timeout=10m0s /tmp/go-build299607628/b500/vet.cfg g_.a -trimpath x_amd64/link -p google.golang.or/tmp/go-build556243166/b360/vet.cfg -lang=go1.24 x_amd64/link -ato�� khb6c8mIR -buildtags x_amd64/vet -errorsas -ifaceassert -nilfunc x_amd64/vet (dns block)
• this-host-does-not-exist-12345.com
  • Triggering command: /tmp/go-build2287418252/b518/mcp.test /tmp/go-build2287418252/b518/mcp.test -test.testlogfile=/tmp/go-build2287418252/b518/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true 7418252/b157/_pk-errorsas .cfg ache/go/1.25.9/x-nilfunc -p errors -lang=go1.25 ache/go/1.25.9/x-importcfg (dns block)
  • Triggering command: /tmp/go-build299607628/b522/mcp.test /tmp/go-build299607628/b522/mcp.test -test.testlogfile=/tmp/go-build299607628/b522/testlog.txt -test.paniconexit0 -test.timeout=10m0s -ato�� -bool -buildtags x_amd64/vet -errorsas -ifaceassert -nilfunc x_amd64/vet e=/t�� t0 m0s x_amd64/vet ache/go/1.25.9/xbash .cfg 64/pkg/tool/linu--version LP5OZdq/DvfQTWCuBUFu78y3ZbmN (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

Pull request overview

This PR updates the Cobra CLI layer to fix failing completion tests (now that some completions are annotation-based), and improves --help output by adding command examples and grouping subcommands.

Changes:

• Fixes TestRegisterFlagCompletions to assert on Cobra flag annotations for filename/dirname completion helpers.
• Adds Example help sections and introduces command groups (modes, utils) with GroupID assignments.
• Updates comments and test helpers to explain/handle Cobra PersistentPreRunE override behavior and GroupID requirements.

Show a summary per file

File	Description
internal/cmd/root.go	Adds root-level Example and registers Cobra command groups (modes, utils).
internal/cmd/proxy.go	Adds proxy Example, assigns GroupID: modes, and clarifies why some flags are redeclared.
internal/cmd/flags_test.go	Updates completion tests to check annotation-based completions for file/dir flags.
internal/cmd/completion_test.go	Ensures test roots define the utils group so completion’s GroupID is valid in isolation.
internal/cmd/completion.go	Assigns GroupID: utils to the completion command and expands the PersistentPreRunE override comment.

Copilot's findings

Tip

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

• Files reviewed: 5/5 changed files
• Comments generated: 3