upgrade

Documentation

Overview

Package upgrade implements release channel selection and version resolution for the `nself upgrade` command.

Three channels are supported:

• stable: public releases (tags matching `vX.Y.Z` with no suffix).
• rc: release candidates (tags matching `vX.Y.Z-rc<N>`).
• edge: nightly / pre-rc (tags matching `vX.Y.Z-edge.<date>.<sha>`).

Channel preference is persisted to ~/.config/nself/channel.json so repeated `nself upgrade` invocations default to the user's chosen channel.

For Homebrew-installed users, each channel maps to a distinct formula name (`nself`, `nself-rc`, `nself-edge`) so `brew upgrade nself-rc` pulls the rc lineage without crossing channels.

Cross-ref:

• .claude/docs/operations/rc-tagging.md (tag format + graduation flow)
• cmd/commands/upgrade.go (command wiring)
• S34-T07 (channels) + S34-T08 (--channel flag)

Index

• Constants
• Variables
• func ConfigPath() string
• func FormulaName(c Channel) string
• func IsValid(s string) bool
• func PingAPIEndpoint(c Channel) string
• func SaveChannel(c Channel) error
• func TagSuffix(c Channel) string
• type Channel
  • func ClassifyTag(tag string) Channel
  • func LoadChannel() Channel
  • func Parse(s string) (Channel, error)

Constants

const DefaultChannel = ChannelStable

DefaultChannel is the channel used when no preference has been saved.

Variables

var AllChannels = []Channel{ChannelStable, ChannelRC, ChannelEdge}

AllChannels lists every accepted channel name, in display order.

Functions

func ConfigPath

func ConfigPath() string

ConfigPath returns the absolute path to the channel preference file. If the user's home directory cannot be determined, a temp-dir fallback is returned so the CLI never panics on a broken environment.

func FormulaName

func FormulaName(c Channel) string

FormulaName returns the Homebrew formula name for the given channel.

stable -> "nself"
rc     -> "nself-rc"
edge   -> "nself-edge"

Separate formulae per channel let Homebrew users pin to a channel via `brew upgrade nself-rc` without crossing into stable.

func IsValid

func IsValid(s string) bool

IsValid returns true if s is one of the accepted channel names.

func PingAPIEndpoint

func PingAPIEndpoint(c Channel) string

PingAPIEndpoint returns the ping.nself.org endpoint that serves the latest release tag for the given channel. ping_api proxies the GitHub releases API and caches results to avoid GitHub rate limits for offline/enterprise users.

stable -> https://ping.nself.org/release/stable/latest
rc     -> https://ping.nself.org/release/rc/latest
edge   -> https://ping.nself.org/release/edge/latest

Response body: `{"tag": "v1.0.9", "url": "https://github.com/...", "sha256": "..."}`

func SaveChannel

func SaveChannel(c Channel) error

SaveChannel persists the user's channel preference to ConfigPath. The parent directory is created at 0755 if missing. The config file itself is written at 0644 since it contains no secrets (just "stable" / "rc" / "edge").

func TagSuffix

func TagSuffix(c Channel) string

TagSuffix returns the version-tag suffix convention for the channel.

stable -> ""         (e.g. v1.0.9)
rc     -> "-rc"      (e.g. v1.0.9-rc3)
edge   -> "-edge"    (e.g. v1.0.9-edge.20260418.a3f7c21)

Callers use this to filter the GitHub releases list when resolving the latest tag on a channel.

Types

type Channel

type Channel string

Channel is one of the three supported release channels.

const (
	ChannelStable Channel = "stable"
	ChannelRC     Channel = "rc"
	ChannelEdge   Channel = "edge"
)

func ClassifyTag

func ClassifyTag(tag string) Channel

ClassifyTag returns the channel a given tag belongs to based on its suffix.

"v1.0.9"                          -> stable
"v1.0.9-rc1"                      -> rc
"v1.0.9-edge.20260418.a3f7c21"    -> edge

Tags that do not match any known pattern are classified as stable (the safest default for unexpected tag shapes).

func LoadChannel

func LoadChannel() Channel

LoadChannel reads the persisted channel preference, returning DefaultChannel if none is set or the file is unreadable or malformed. Failure to read is never fatal — a missing or corrupt file simply falls back to stable.

func Parse

func Parse(s string) (Channel, error)

Parse returns the Channel value for s, or an error if s is not a valid channel name.