Documentation
¶
Overview ¶
Package update discovers whether a newer circleci release exists and, when so, hands the caller a notice to print after a successful command. It never blocks the command, corrupts piped output, or surfaces its own errors.
Index ¶
- Constants
- func EffectiveVersion(version string) string
- func IsNewer(latest, current string) bool
- func PrintBinaryNotice(ctx context.Context, binaryName, installedVersion, latestVersion string)
- func PrintReleaseNotice(ctx context.Context, currentVersion string, rel *ReleaseInfo, ...)
- func ShouldCheck(ctx context.Context, cfg *config.Config, version string) bool
- type Notifier
- type ReleaseInfo
- type Source
Constants ¶
const ( // ToolName is the value sent as filter[tool] and echoed back as the "tool" // attribute. It is the CLI's GitHub repository name and part of the server's // public contract, so it must never be derived from anything dynamic. ToolName = "circleci-cli" // ForceEnv bypasses the TTY and dev-build gates and supplies the version to // treat as current. Internal test hook (double underscore); never user-set. ForceEnv = "__CIRCLE_UPDATE_FORCE" // CacheWindow is how often we are willing to hit the network. Matched to our // ~daily release cadence so the version we advertise never lags reality by // more than about a day: a longer window would keep pointing at a stale // "latest" (still a correct nag, just an out-of-date target) while a shorter // one would probe more often than a new release can appear. CacheWindow = 24 * time.Hour )
Variables ¶
This section is empty.
Functions ¶
func EffectiveVersion ¶
EffectiveVersion returns the version the check should treat as current: the ForceEnv override when set (test hook), otherwise version.
func IsNewer ¶ added in v1.0.48210
IsNewer reports whether latest is a strictly greater semver than current, after normalising a git-describe current version.
func PrintBinaryNotice ¶ added in v1.0.48210
PrintBinaryNotice writes the update notice to stderr for the given binary and version.
func PrintReleaseNotice ¶ added in v1.0.48210
func PrintReleaseNotice(ctx context.Context, currentVersion string, rel *ReleaseInfo, upgradeCommand string)
PrintReleaseNotice writes the update notice to stderr, blank-line padded and after all command output: the version transition, then the command that upgrades this install when upgradeCommand is known, then the new release's GitHub page. It is a no-op when rel is nil.
The notice only prints when both Out and Err are TTYs (see ShouldCheck), so color is always safe here — there is no pipe to corrupt. The color helpers still fall back to plain text under NO_COLOR / TERM=dumb, so the message text is unchanged when color is disabled.
func ShouldCheck ¶
ShouldCheck reports whether this invocation may perform an update check.
Agents and MCP cannot act on a prompt, and the notice must never corrupt a pipe — so a detected agent or a non-TTY stream silences it. No token is required: GET /api/v3/tool/releases serves anonymously, so unauthenticated users (fresh installs, config-validate-only) still get the notice. ForceEnv bypasses the TTY and dev-build gates for tests but not the agent/preference gates.
Types ¶
type Notifier ¶
type Notifier struct {
// contains filtered or unexported fields
}
Notifier carries a background update check. Create one with Start, then call Finish once the command has produced all its output.
func Start ¶
Start launches an update check in the background against src. The check runs with a child of ctx so Finish can cancel any in-flight request.
func (*Notifier) Finish ¶
func (n *Notifier) Finish() *ReleaseInfo
Finish returns the release worth telling the user about, or nil. It cancels any in-flight request first (so a slow request never adds command latency) and then blocks until the background check settles — bounded, because the cancel aborts the request.
type ReleaseInfo ¶
type ReleaseInfo struct {
Version string // semver, no leading "v" — matches main.version
PublishedAt time.Time // zero when unknown; treated as "notify"
}
ReleaseInfo is the newest stable release the source reported.
func Check ¶
Check returns a release worth telling the user about, or nil. It refreshes from src at most once per CacheWindow, but evaluates notifyDelay against cached state on every call — so a notice suppressed by the delay appears the moment the delay elapses, without waiting for the next network fetch.
Errors are best-effort: a contended lock or unreadable state returns nil, nil rather than surfacing, because an update check is the last thing that should ever print an error.
func Latest ¶ added in v1.3.0
func Latest(ctx context.Context, src Source, statePath string) *ReleaseInfo
Latest returns the newest stable release, or nil when none is known. It shares Check's cache, so it reaches the network at most once per CacheWindow, but it applies no notify delay: it answers "what is the newest release", not "is it time to tell the user". The fetch is bounded by latestTimeout so a caller that waits on it, unlike the background notifier, stays fast offline.
type Source ¶
type Source interface {
Latest(ctx context.Context) (*ReleaseInfo, error)
}
Source returns the newest stable release, or nil if it cannot tell. proxySource (GET /api/v3/tool/releases) is the only implementation; see the package plan for the contingency it exists for.
func NewProxySource ¶
NewProxySource returns the Source backed by GET /api/v3/tool/releases.
Source Files