Documentation
¶
Overview ¶
Package cobracmd builds a ready-made self-update Cobra command from a selfupdate.Config. It is the ONLY place in this module that imports Cobra (REQ: cobra-adapter-optional) — the root selfupdate package has no command-framework dependency, so a CLI built on something else, or on nothing, can call Config.Update and Config.Check directly.
Everything this package prints, and every exit code the host process eventually uses, is the host's own decision. The command's RunE never calls os.Exit and never picks a code itself (REQ: host-owned-exit-codes): it returns nil, or whatever CommandOptions.Errors.Failure or .UpdateAvailable produced, and the host's own top-level runner is what turns that into a process exit code — which is exactly what lets two consumers with incompatible exit-code contracts (one reserving a dedicated code for "update available", one folding it into a general findings code) both build a working command from this same adapter.
The prompting, refusal, and output-formatting logic RunE actually performs lives in the cliui subpackage, which imports neither Cobra nor any other command framework — this package is only the Cobra flag/wiring layer on top of it, kept as the ONE place that logic is implemented so a CLI with no framework at all (see cliui's own doc comment) can reuse it directly instead of re-deriving it.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(cfg selfupdate.Config, opts CommandOptions) *cobra.Command
New builds the "self-update" command for cfg. It registers --check, --yes/-y, --version (a pinned release tag, distinct from any root-level --version the host itself defines), --allow-downgrade, --dry-run, and — when opts.JSONFormat is set — --format.
RunE performs no work itself beyond flag parsing, calling selfupdate.Config.Check or .Update, and formatting the result via cliui: all decision logic lives in the core package, per REQ: no-io-side-effects- in-core — this adapter is where the I/O those decisions require (prompting, printing, choosing an output format) is allowed to live.
Types ¶
type CommandOptions ¶
type CommandOptions struct {
// Use is the command name. Defaults to "self-update".
Use string
// Short is the one-line help text. Defaults to a generic description.
Short string
// Aliases are additional names the command responds to, e.g.
// []string{"update"}.
Aliases []string
// Errors maps outcomes to the host's own error type. Required for a
// host that wants distinguishable exit codes; a nil Errors makes every
// failure and every "update available" --check both return the
// underlying error/nil unchanged.
Errors ErrorMapper
// JSONFormat registers a --format text|json flag when true. When false,
// output is always the human-readable text form.
JSONFormat bool
// Interactive reports whether the process is attached to an interactive
// terminal, used to implement REQ: non-interactive-refusal. Passed
// straight through to cliui.ConfirmOptions.Interactive; nil means that
// package's own default (cliui.IsTerminal, a term.IsTerminal check on
// stdin — never an os.ModeCharDevice check, which /dev/null also
// satisfies). Tests should always override this — it is the seam that
// makes the confirmation-prompt and non-interactive-refusal paths
// exercisable without a real TTY.
Interactive func() bool
// AfterUpdate runs after a successful update outcome. It is passed through
// to selfupdate.Options so non-Cobra and Cobra consumers share the same
// post-update contract. Its errors are warnings on the returned Outcome,
// never command failures after the binary update completed.
AfterUpdate selfupdate.AfterUpdateFunc
}
CommandOptions configures the command New builds. Use and Short default to "self-update" and a generic short description when left empty.
type ErrorMapper ¶
type ErrorMapper interface {
// Failure maps a non-nil command error into the host's own error type.
// Invalid output formats return *UsageError; update and check failures
// ordinarily return *selfupdate.Failure. Output writer errors are also
// mapped so hosts can preserve their operational-failure exit codes.
Failure(err error) error
// UpdateAvailable is called after a successful --check whose verdict is
// neither UpToDate nor Ahead — that covers both selfupdate.
// UpdateAvailable and selfupdate.Undetermined, since neither is "up to
// date" (a consumer that wants a dedicated exit code for "update
// available" typically wants it for both). selfupdate.Ahead is excluded
// the same as UpToDate (REQ: ahead-of-latest): a build ahead of the
// latest stable release has nothing to update to, so it must never
// signal "update available" — a machine on a source or pseudo-version
// build must not trip this forever. Returning nil reports success (exit
// 0) despite an update being available; returning an error is how a
// consumer reserves e.g. a dedicated exit code for this case.
UpdateAvailable(res selfupdate.CheckResult) error
}
ErrorMapper translates this package's typed outcomes into the host CLI's own error type/exit-code convention. Both methods may return the error unchanged (or nil) — the mapper exists for hosts that need to wrap or reclassify, not because every host must.
type UsageError ¶
type UsageError struct{ Err error }
UsageError identifies invalid command input before any update work begins. Hosts may use errors.As to distinguish it from operational failures.
func (*UsageError) Error ¶
func (e *UsageError) Error() string
func (*UsageError) Unwrap ¶
func (e *UsageError) Unwrap() error
Source Files