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
}
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 error from Config.Update or Config.Check —
// ordinarily a *selfupdate.Failure, unwrap-able via
// selfupdate.KindOf(err) — into the host's own error type.
Failure(err error) error
// UpdateAvailable is called after a successful --check whose verdict is
// not UpToDate — 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). 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.
Source Files