upgrade

Documentation

Overview

Package upgrade provides the upgrade executor for managed tools. It sits ON TOP of the read-only internal/update package and is deliberately isolated from install, pipeline, planner, and config-sync code paths.

Import boundary: this package MUST NOT import:

• github.com/Gabrielvilabracho/selops-ai/internal/pipeline
• github.com/Gabrielvilabracho/selops-ai/internal/planner
• github.com/Gabrielvilabracho/selops-ai/internal/cli

Index

• Variables
• func AsManualFallback(err error) (string, bool)
• func Download(ctx context.Context, r update.UpdateResult, profile system.PlatformProfile) error
• func RenderUpgradeReport(report UpgradeReport) string
• type CLISpinner
  • func NewSpinner(w io.Writer, message string) *CLISpinner
  • func (s *CLISpinner) Finish(success bool)
  • func (s *CLISpinner) FinishSkipped()
• type ExecuteOptions
• type ManualFallbackError
  • func (e *ManualFallbackError) Error() string
• type ToolUpgradeResult
• type ToolUpgradeStatus
• type UpgradeReport
  • func Execute(ctx context.Context, results []update.UpdateResult, ...) UpgradeReport
  • func ExecuteWithOptions(ctx context.Context, results []update.UpdateResult, ...) UpgradeReport

Variables

var AppVersion = "dev"

AppVersion is the gentle-ai version written into backup manifests created by the upgrade executor. Set by app.go before calling Execute so that upgrade backups record the version that created them. Default "dev" matches the ldflags default in app.Version.

Functions

func AsManualFallback

func AsManualFallback(err error) (string, bool)

AsManualFallback unwraps err to check if it is a ManualFallbackError. Returns (hint, true) when it is, ("", false) otherwise.

func Download

func Download(ctx context.Context, r update.UpdateResult, profile system.PlatformProfile) error

Download downloads the GitHub release binary for the given tool, verifies its SHA256 checksum against the release's checksums.txt, and replaces the installed binary atomically.

Checksum verification is mandatory: the install fails if checksums.txt is unavailable, if the archive is not listed, or if the digest does not match.

This function is not called on Windows — callers (strategy.go) gate it via platform check and return a manual fallback error instead.

func RenderUpgradeReport

func RenderUpgradeReport(report UpgradeReport) string

RenderUpgradeReport produces a plain-text report of upgrade results. Designed for the CLI path — no lipgloss, no color.

Types

type CLISpinner

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

func NewSpinner

func NewSpinner(w io.Writer, message string) *CLISpinner

func (*CLISpinner) Finish

func (s *CLISpinner) Finish(success bool)

func (*CLISpinner) FinishSkipped

func (s *CLISpinner) FinishSkipped()

FinishSkipped stops the spinner and renders a skip marker (--) instead of the failure marker (✗). Use this for intentional skips such as manual-update fallbacks on Windows — these are NOT failures and must not be displayed as such.

type ExecuteOptions

type ExecuteOptions struct {
	Progress          io.Writer
	BackupDiagnostics io.Writer
	SkipBackup        bool
}

ExecuteOptions controls optional upgrade executor behavior.

Progress is for user-visible spinner/status output. BackupDiagnostics is for verbose backup walk diagnostics; nil keeps backup enumeration silent, which prevents background TUI jobs from writing over the Bubble Tea screen.

SkipBackup, when true, skips both creating a pre-upgrade backup snapshot AND retention pruning of the backup directory. Use this when the user explicitly opts out of backup behavior for a single run (CLI: --no-backup). The default (false) preserves the original safe-by-default behavior.

type ManualFallbackError

type ManualFallbackError struct {
	Hint string
}

ManualFallbackError signals that a tool requires manual intervention rather than automated upgrade. Callers (e.g. executeOne) must treat this as UpgradeSkipped with ManualHint populated — NOT as UpgradeFailed.

func (*ManualFallbackError) Error

func (e *ManualFallbackError) Error() string

type ToolUpgradeResult

type ToolUpgradeResult struct {
	ToolName   string
	OldVersion string
	NewVersion string
	Method     update.InstallMethod
	Status     ToolUpgradeStatus
	Err        error
	// ManualHint is set when the tool requires manual intervention instead of
	// automated upgrade (e.g. Windows self-replace, unsupported binary path).
	ManualHint string
}

ToolUpgradeResult holds the outcome of upgrading a single tool.

type ToolUpgradeStatus

type ToolUpgradeStatus string

ToolUpgradeStatus describes the outcome of a single tool upgrade attempt.

const (
	UpgradeSucceeded ToolUpgradeStatus = "succeeded"
	UpgradeFailed    ToolUpgradeStatus = "failed"
	UpgradeSkipped   ToolUpgradeStatus = "skipped" // dry-run, dev build, or unsupported platform
)

type UpgradeReport

type UpgradeReport struct {
	// BackupID is the snapshot ID created before upgrade execution.
	// Empty when no upgrades were executed (nothing to back up).
	BackupID string

	// BackupWarning is set when backup creation was attempted but failed.
	// A non-empty value means the upgrade ran without a pre-execution backup.
	// This surfaces the G6 gap: backup failures are no longer silently skipped.
	BackupWarning string

	Results []ToolUpgradeResult
	DryRun  bool
}

UpgradeReport is the top-level result returned by Execute.

func Execute

func Execute(ctx context.Context, results []update.UpdateResult, profile system.PlatformProfile, homeDir string, dryRun bool, progress ...io.Writer) UpgradeReport

Execute evaluates UpdateResults, snapshots config before execution, then runs the appropriate upgrade strategy for each eligible tool.

Reporting rules:

• Status UpdateAvailable → attempt upgrade; report Succeeded/Failed/Skipped(manual)
• Status DevBuild → report as UpgradeSkipped with ManualHint (dev/source build)
• Status VersionUnknown → report as UpgradeSkipped with ManualHint (manual attention required)
• Status RegisteredNotMaterialized → attempt OpenCode npm dependency installation/update
• Status UpToDate, NotInstalled, CheckFailed → omitted from report
• dryRun=true → no exec; eligible tools reported as UpgradeSkipped

The backup snapshot is created before any exec call — this is the architectural guarantee that config is safe even if an upgrade fails mid-way.

func ExecuteWithOptions

func ExecuteWithOptions(ctx context.Context, results []update.UpdateResult, profile system.PlatformProfile, homeDir string, dryRun bool, options ExecuteOptions) UpgradeReport