updater

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 deliberately does not define a behavioural Updater interface over Check/Update: each mechanism's Channel enum differs, and nothing drives an updater polymorphically. The clog dependency lives here and in the subpackages, keeping the core clive package dependency-light.

Index

• Variables
• func CompleteReport(res *fx.WaitResult, name string, info clive.Info, old, current string) error
• func CompleteUpToDate(res *fx.WaitResult, name string, info clive.Info, ver string) error
• func DisplayName(name, binary string) string
• func GoPrivate(module, existing string) string
• func HintFor(tool Tool, current, latest string, opts ...HintOption)
• func InstallDir(dir string) string
• func ProxyBypass() []string
• func Report(name string, info clive.Info, old, current string)
• func Spin(ctx context.Context, msg string, fn func(context.Context) error, ...) error
• func SpinResult(ctx context.Context, msg string, fn func(context.Context) error, ...) *fx.WaitResult
• func SpinTimeout(ctx context.Context, msg, timeoutMsg string, timeout time.Duration, ...) error
• func TransientSpinResult(ctx context.Context, msg string, fn func(context.Context) error, ...) *fx.WaitResult
• func UpToDate(name string, info clive.Info, ver string)
• type Field
• type HintOption
  • func WithOutdatedHintColor(c color.Color) HintOption
  • func WithOutdatedHintSymbol(symbol string) HintOption
• type OutdatedHint
  • func NewOutdatedHint(opts ...HintOption) OutdatedHint
  • func (h OutdatedHint) Log(displayName, binaryName, installed, latest string)
• type Tool

Variables

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

DefaultHintColor is the orange accent for the update hint message.

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

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

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 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 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 SpinResult

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

func SpinTimeout(
	ctx context.Context,
	msg, 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 logs the normal completion line (with elapsed). A context cancellation (e.g. Ctrl-C) is not a timeout and falls through to the silent path.

func TransientSpinResult

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 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

type HintOption func(*OutdatedHint)

HintOption configures an OutdatedHint.

func WithOutdatedHintColor

func WithOutdatedHintColor(c color.Color) HintOption

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

func WithOutdatedHintSymbol

func WithOutdatedHintSymbol(symbol string) HintOption

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

type OutdatedHint

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

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

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 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.