updater

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 6, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package updater holds the shared surface for clive's self-update mechanisms. Each mechanism is a sibling subpackage - brew (Homebrew), goinstall (`go install`), and github (release assets) - that describes a tool with its own Config and exposes Check/Update. This package owns the pieces those Configs have in common: the Tool interface that consumers such as notify depend on, and the cross-mechanism UX helpers (Report, UpToDate, Spin), install directory resolution (InstallDir), and subprocess-environment helpers (ProxyBypass, GoPrivate).

It also defines the behavioural Updater interface, satisfied by every mechanism's Config, so a consumer can drive self-updates without knowing the install method; the dev/stable flag pair is the common channel currency each mechanism maps onto its own Channel enum. The clog dependency lives here and in the subpackages, keeping the core clive package dependency-light.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultHintColor color.Color = lipgloss.Color("208")

DefaultHintColor is the orange accent for the update hint message.

View Source 
var ErrReported = errors.New("update failed")

ErrReported marks a failure that has already been shown to the user - a spinner step finalized at error level (e.g. by SpinTimeout) - so its message is on screen. A consumer should treat it as a plain non-zero exit and not log a second, generic failure line on top of the one already printed.

Functions

func CompleteReport added in v0.1.8 

func CompleteReport(res *fx.WaitResult, name string, info clive.Info, old, current string) error

CompleteReport emits the update result as the completion line for a spinner result, replacing that spinner's transient progress line in TTY output.

func CompleteUpToDate added in v0.1.8 

func CompleteUpToDate(res *fx.WaitResult, name string, info clive.Info, ver string) error

CompleteUpToDate emits the up-to-date notice as a spinner completion line.

func DisplayName 

func DisplayName(name, binary string) string

DisplayName resolves the human-facing name shown in messages: name when set, else the binary name. Shared by every mechanism's Config.DisplayName.

func GoPrivate 

func GoPrivate(module, existing string) string

GoPrivate returns a GOPRIVATE value that includes module, preserving any existing entries so the caller's configuration is not discarded. Both inputs are trimmed so surrounding whitespace never yields a malformed list.

func HintFor 

func HintFor(tool Tool, current, latest string, opts ...HintOption)

HintFor logs the update hint for a tool, stripping a leading "v" and formatting each version through the tool's VersionLink. Options customize the presentation (e.g. WithOutdatedHintSymbol).

func InstallDir 

func InstallDir(dir string) string

InstallDir resolves the directory a binary is installed into: dir when set (with a leading "~/" and any env vars expanded), else ~/.local/bin. It returns "" only when no dir was given and the home directory cannot be resolved, letting a caller fall back to a mechanism-specific default.

func MessageStyle added in v0.3.0 

func MessageStyle() *lipgloss.Style

MessageStyle returns the message-text style for the updater's lines, for the sub-packages (e.g. brew) that emit a line themselves and want it to match the shared helpers' message styling.

func ProxyBypass 

func ProxyBypass() []string

ProxyBypass returns env entries that disable any inherited proxy for an update subprocess: each proxy variable is blanked (an empty value overrides the inherited one) and NO_PROXY is set to "*" so every host is exempt. Both the upper- and lower-case spellings are set, as tools read either.

func Report 

func Report(name string, info clive.Info, old, current string)

Report logs the result of an update as an old→new pair when the version changed, and otherwise defers to UpToDate. Both old and current may carry a leading "v"; it is stripped before comparison and display.

func SetSymbols added in v0.3.0 

func SetSymbols(opts ...SymbolOption)

SetSymbols applies opts to the package-level glyph set used by Report, UpToDate, Spin, and their completion-line variants. Only the glyphs (and colours) named by opts change; everything unspecified keeps its current value, so a caller overrides just what it needs and the rest retain their defaults.

func Spin 

func Spin(ctx context.Context, msg string, fn func(context.Context) error, fields ...Field) error

Spin runs fn under a clog spinner labelled msg, with any fields attached: on success it logs a completion line, and on failure it returns fn's error without the spinner logging its own error line, so the caller reports the failure exactly once.

func SpinProgress added in v0.3.1 

func SpinProgress(
	ctx context.Context,
	msg string,
	fn func(context.Context, *fx.Update) error,
	fields ...Field,
) error

SpinProgress is Spin where fn additionally receives the spinner's live fx.Update, letting it revise the running label mid-flight (e.g. switch to a "Waiting ..." message while it blocks). The success completion line still uses msg, so a temporary relabel does not change what is committed to scrollback.

func SpinResult added in v0.1.8 

func SpinResult(
	ctx context.Context,
	msg string,
	fn func(context.Context) error,
	fields ...Field,
) *fx.WaitResult

SpinResult runs fn under a clog spinner labelled msg and returns the unfinalized result so callers can choose the completion line.

func SpinTimeout added in v0.2.0 

func SpinTimeout(
	ctx context.Context,
	msg, doneMsg, timeoutMsg string,
	timeout time.Duration,
	fn func(context.Context) error,
) error

SpinTimeout runs fn under a spinner like Spin, but bounds it with timeout. On a clean timeout it supplants the spinner with timeoutMsg at error level, swapping the spinner's elapsed field for a timeout one naming the bound that was hit, so the line reads e.g. "Timed out ... timeout=2m" rather than clearing or surfacing the killed subprocess's opaque error - and returns ErrReported so the caller can exit non-zero without a consumer double-reporting. Any other failure behaves like Spin (silent spinner, fn's error returned for the caller to report); success supplants the spinner with doneMsg (with elapsed), so the finished line can read "Fetched ..." in place of the running "Fetching ..." label. A context cancellation (e.g. Ctrl-C) is not a timeout and falls through to the silent path.

func SpinTimeoutProgress added in v0.3.1 

func SpinTimeoutProgress(
	ctx context.Context,
	msg, doneMsg, timeoutMsg string,
	timeout time.Duration,
	fn func(context.Context, *fx.Update) error,
) error

SpinTimeoutProgress is SpinTimeout where fn is additionally handed the spinner's live fx.Update, letting it revise the running label mid-flight - e.g. to switch "Fetching ..." to "Waiting for another process ..." while it blocks - without disturbing the timeout, done, and error handling.

func TransientSpinResult added in v0.1.8 

func TransientSpinResult(
	ctx context.Context,
	msg string,
	fn func(context.Context) error,
	fields ...Field,
) *fx.WaitResult

TransientSpinResult is like SpinResult, but suppresses the non-TTY progress line so only the caller's final completion message is written to scrollback.

func TransientSpinResultProgress added in v0.3.1 

func TransientSpinResultProgress(
	ctx context.Context,
	msg string,
	fn func(context.Context, *fx.Update) error,
	fields ...Field,
) *fx.WaitResult

TransientSpinResultProgress is TransientSpinResult where fn additionally receives the spinner's live fx.Update to revise the running label mid-flight.

func TrashSymbol added in v0.3.0 

func TrashSymbol() string

TrashSymbol returns the current trash glyph, already coloured if a colour was set, for the sub-packages (e.g. brew) that emit the stray-copy line themselves rather than through this package's shared helpers.

func UpToDate 

func UpToDate(name string, info clive.Info, ver string)

UpToDate reports that no update was applied, including the version field only when a version is known (a go-run build has none to show).

Types

type Field 

type Field struct {
	Key string
	Val string
}

Field is an optional structured key/value attached to a Spin message, shown on both the spinner and its completion line (e.g. version="1.2.3").

type HintOption added in v0.1.3 

type HintOption func(*OutdatedHint)

HintOption configures an OutdatedHint.

func WithOutdatedHintColor added in v0.1.3 

func WithOutdatedHintColor(c color.Color) HintOption

WithOutdatedHintColor overrides the message accent colour (default orange). A nil colour is ignored.

func WithOutdatedHintSymbol added in v0.1.3 

func WithOutdatedHintSymbol(symbol string) HintOption

WithOutdatedHintSymbol overrides the hint's leading glyph (default 💡).

type OutdatedHint added in v0.1.3 

type OutdatedHint struct {
	// contains filtered or unexported fields
}

OutdatedHint renders the shared "you're behind" update hint. Build one with NewOutdatedHint and options, then call OutdatedHint.Log.

func NewOutdatedHint added in v0.1.3 

func NewOutdatedHint(opts ...HintOption) OutdatedHint

NewOutdatedHint builds a hint with defaults - 💡, an orange message, a red installed version and a green latest version - then applies opts.

func (OutdatedHint) Log added in v0.1.3 

func (h OutdatedHint) Log(displayName, binaryName, installed, latest string)

Log renders the hint: the symbol, the installed (red) and latest (green) versions as fields, and a coloured "<name> is outdated - run `<binary> update` to upgrade!" message with the command emphasised. The colours are applied to the values here rather than via global clog styles, so a host's own field formatting is never affected. installed and latest are already display-formatted.

type SymbolOption added in v0.3.0 

type SymbolOption func()

SymbolOption overrides one of the updater's log glyphs (or its colour). Apply it with SetSymbols.

func WithDoneColor added in v0.3.0 

func WithDoneColor(c color.Color) SymbolOption

WithDoneColor colours the completed-spinner-step glyph; nil (the default) leaves clog's per-level symbol style in charge.

func WithDoneSymbol added in v0.3.0 

func WithDoneSymbol(s string) SymbolOption

WithDoneSymbol overrides the completed-spinner-step glyph (default ✅).

func WithDowngradedColor added in v0.3.0 

func WithDowngradedColor(c color.Color) SymbolOption

WithDowngradedColor colours the downgrade glyph; nil (the default) leaves clog's per-level symbol style in charge.

func WithDowngradedSymbol added in v0.3.0 

func WithDowngradedSymbol(s string) SymbolOption

WithDowngradedSymbol overrides the downgrade glyph (default ⬇️).

func WithMessageColor added in v0.3.0 

func WithMessageColor(c color.Color) SymbolOption

WithMessageColor colours the message text on the updater's lines. The default (nil) renders the message plain, ignoring the host's per-level message style so the updater's lines read consistently regardless of the host's theme.

func WithTrashColor added in v0.3.0 

func WithTrashColor(c color.Color) SymbolOption

WithTrashColor colours the stray-copy glyph; nil (the default) leaves clog's per-level symbol style in charge.

func WithTrashSymbol added in v0.3.0 

func WithTrashSymbol(s string) SymbolOption

WithTrashSymbol overrides the glyph on the line reporting a stray non-Homebrew copy being trashed or removed (default 🗑️).

func WithUpToDateColor added in v0.3.0 

func WithUpToDateColor(c color.Color) SymbolOption

WithUpToDateColor colours the "already up-to-date" glyph; nil (the default) leaves clog's per-level symbol style in charge.

func WithUpToDateSymbol added in v0.3.0 

func WithUpToDateSymbol(s string) SymbolOption

WithUpToDateSymbol overrides the "already up-to-date" glyph (default 🚀).

func WithUpgradedColor added in v0.3.0 

func WithUpgradedColor(c color.Color) SymbolOption

WithUpgradedColor colours the upgrade glyph; nil (the default) leaves clog's per-level symbol style in charge.

func WithUpgradedSymbol added in v0.3.0 

func WithUpgradedSymbol(s string) SymbolOption

WithUpgradedSymbol overrides the upgrade glyph (default ⬆️).

type Tool 

type Tool interface {
	// BinaryName is the executable/command name, e.g. "myapp".
	BinaryName() string
	// DisplayName is the human-facing name shown in messages.
	DisplayName() string
	// VersionLink renders v as a clickable link to its release/commit.
	VersionLink(v string) string
	// LatestRef returns the newest installable ref of the tool, fetched over the
	// network without a toolchain so a distributed binary can call it. Each
	// mechanism answers in its own currency: brew and goinstall report the
	// highest semver tag in the repository, while github - which installs release
	// assets - reports the latest release's tag, so a consumer's "update
	// available" signal matches what the updater can actually fetch. A nil client
	// uses [http.DefaultClient].
	LatestRef(ctx context.Context, client *http.Client) (string, error)
}

Tool is the metadata a consumer needs to describe a self-updating CLI without depending on how it updates. The brew, goinstall, and github Configs each satisfy it. VersionLink and LatestRef are methods rather than an Info() accessor because Config carries Info as a field, and a struct cannot expose both a field Info and a method Info.

type Updater added in v0.2.7 

type Updater interface {
	Tool
	// Check reports whether an update is available without installing it.
	Check(ctx context.Context) error
	// Update installs the latest release from the selected channel.
	Update(ctx context.Context, dev, stable bool) error
}

Updater is a Tool that can also check for and install updates of itself. The dev/stable pair maps onto each mechanism's own channels: brew installs the latest tagged release for stable and a source build for dev; goinstall treats dev as the tip of the dev branch; github treats dev as the newest prerelease. Neither set selects the mechanism's default channel, and stable is meaningful only to brew (the other mechanisms' defaults already are the latest stable release).

Source Files

View all Source files

Directories

Path Synopsis
Package brew self-updates a Go CLI binary through Homebrew.
 Package brew self-updates a Go CLI binary through Homebrew.
Package github self-updates a Go CLI binary from its GitHub releases.
 Package github self-updates a Go CLI binary from its GitHub releases.
Package goinstall self-updates a Go CLI binary through `go install`.
 Package goinstall self-updates a Go CLI binary through `go install`.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.