microcks / microcks/microcks-cli

Refactor CLI error handling to idiomatic Cobra RunE pattern for improved testability and maintainability

Open
#322 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
52
Forks
68
Avg merge
6h 54m
Merged PRs (30d)
10

Description

### Reason/Context

The current CLI implementation relies heavily on `errors.CheckError()` and `Run` handlers, which causes abrupt termination of commands and reduces testability.

This pattern makes it difficult to:
- properly propagate errors through Cobra command chain
- write unit tests for command execution
- ensure graceful cleanup of resources
- maintain consistent error formatting across commands

Modern Go CLI tools (such as kubectl, docker CLI) prefer using `RunE` and returning errors up the call stack for centralized handling.

This improvement is motivated by the need to align the CLI with idiomatic Go practices and improve long-term maintainability and developer experience.

### Description

This enhancement proposes a gradual refactor of the CLI command execution model from `Run` + `errors.CheckError()` to Cobra's `RunE` pattern.

Key changes include:
- Replace `Run` functions with `RunE` in command definitions
- Remove direct calls to `errors.CheckError()`
- Return errors using `fmt.Errorf("%w")` for proper wrapping
- Centralize error handling at the root command level
- Ensure `SilenceErrors` is enabled to avoid duplicate error printing
- Preserve existing CLI behavior and user-facing output

This is NOT a breaking change if done incrementally, as each command will be migrated independently.

Expected benefits:
- Improved testability of CLI commands
- Cleaner error propagation model
- Better alignment with idiomatic Go CLI design
- Safer resource cleanup and execution flow
- Easier future extension of CLI features

No user-facing breaking changes are expected if migration is done incrementally.

### Implementation ideas

- Start migration with low-risk commands (e.g., stop, version, context)
- Convert command definitions from `Run` → `RunE`
- Replace `errors.CheckError()` with error returns
- Use `fmt.Errorf("%w")` for error wrapping
- Add centralized error handler in root command
- Add `SilenceErrors: true` in root Cobra command
- Introduce minimal unit tests for migrated commands using RunE
- Validate CLI behavior remains identical after each migration step
- Avoid large-scale refactor; follow incremental PR strategy per command

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the root Cobra command and the stop, version, and context command definitions that currently use Run and errors.CheckError(). Read how errors are currently printed and how commands are tested, then migrate one low-risk command while preserving its user-facing output. Done means errors propagate through RunE, root-level handling avoids duplicate printing, and the migrated command has a unit test.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, testing
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.