selfupdate

type Action int

type AfterUpdate struct {
	Outcome    Outcome
	Executable ExecutableIdentity
}

type AfterUpdateFunc func(ctx context.Context, update AfterUpdate) error

type Availability struct {
	Result    CheckResult
	Target    string
	Pinned    bool
	Detection Detection
	Warning   error
}

type AvailabilityReporter func(Availability)

type CheckResult struct {
	Current string
	Latest  string
	Verdict Verdict
}

type Config struct {
	// BinaryName is the executable name inside the release archive and the
	// first component of the default asset/checksums naming.
	BinaryName string
	// Repository is "owner/repo" on GitHub, e.g. "sneat-dev/wb".
	Repository string
	// CurrentVersion is the running build's own version string, typically
	// stamped at link time. See UndeterminedVersions for builds that can't
	// know this (e.g. a local `go build`).
	CurrentVersion string
	// UndeterminedVersions lists the CurrentVersion values that mean "this
	// build cannot say its version" (e.g. {"dev"} or {"unknown"}). Such a
	// version is reported Undetermined rather than UpToDate or
	// UpdateAvailable, and disables the pinned-downgrade guard, because
	// direction can't be established without a real version to compare from
	// (REQ: undetermined-version). Defaults to {"dev"} when empty — a Go
	// pseudo-version is never in this set implicitly; it orders below its
	// release like any other known version.
	UndeterminedVersions []string
	// Managers are the package managers that might own this binary's
	// install, checked in order by Classify. Empty means the CLI is never
	// distributed through a package manager the caller wants recognized —
	// every install classifies as Manual or Ambiguous.
	Managers []Manager
	// SupportedPlatforms restricts self-replace to the listed GOOS/GOARCH
	// pairs (REQ: unsupported-platform). Empty means all platforms the host
	// Go toolchain runs on are assumed supported.
	SupportedPlatforms []Platform
	// TagPrefix selects which releases belong to this binary when one
	// repository publishes several products, e.g. "cli-" for tags like
	// "cli-v1.2.3". Empty means every release belongs to this binary (the
	// single-product default).
	TagPrefix string
	// VersionProbeArgs are the arguments run against the newly installed
	// binary to confirm it reports the expected version after a swap
	// (REQ: post-swap-version-check). Defaults to {"--version"}.
	VersionProbeArgs []string
	// AssetName names the release archive for one binary/version/platform
	// combination. Defaults to GoReleaser's own convention:
	// "<binary>_<version>_<os>_<arch>.tar.gz" (".zip" on windows), with a
	// leading "v" in version stripped.
	AssetName func(binary, version, goos, goarch string) string
	// ChecksumsName names the release's checksums file for one version.
	// Defaults to GoReleaser's "<binary>_<version>_checksums.txt", with a
	// leading "v" in version stripped.
	ChecksumsName func(binary, version string) string
	// ReleasesAPIURL is the GitHub REST endpoint listing this repository's
	// releases, newest first. Defaults to
	// "https://api.github.com/repos/<Repository>/releases". Overriding it is
	// how this package's own tests point at an httptest.Server instead of
	// the real GitHub API.
	ReleasesAPIURL string
	// DownloadURL builds the download URL for one asset (or the checksums
	// file, which is downloaded the same way) within a specific release.
	// Defaults to that release's OWN GitHub Releases URL —
	// "https://github.com/<repository>/releases/download/<tag>/<asset>" —
	// never the "/releases/latest/download/" alias, which would silently
	// fetch whatever is currently latest instead of the pinned release
	// (REQ: pinned-exact-tag).
	DownloadURL func(repository, tag, asset string) string
	// HTTPClient is used for every GitHub request. Defaults to
	// http.DefaultClient.
	HTTPClient *http.Client
}

type Detection struct {
	// Method is how the binary was installed.
	Method InstallMethod
	// Manager identifies the owning package manager when Method is Managed;
	// nil for Manual and Ambiguous.
	Manager *Manager
	// Path is the resolved path that was classified — after following
	// symlinks when DetectSelf performed the resolution, or exactly the
	// input path when Classify was called directly (as the reference CLI's
	// --explain-path does).
	Path string
}

type ExecutableIdentity struct {
	Path         string
	ResolvedPath string
}

type Failure struct {
	Kind FailureKind
	// Path is the executable path involved, when applicable (set for
	// KindPermission and KindAmbiguous). Empty otherwise.
	Path string
	// Err is the underlying error, always non-nil.
	Err error
}

type FailureKind int

type InstallMethod int

type InstallPlan struct {
	// Tag is the exact published release tag InstallNew will install.
	Tag string
	// Version is Tag's normalized (no leading "v", no TagPrefix) version.
	Version string
	// AssetURL is the exact release-asset URL InstallNew will download —
	// the value details-before-install shows before any confirmation.
	AssetURL string
}

type InstallResult struct {
	// Path is the destination path the verified binary was placed at —
	// always exactly the destPath InstallNew was called with.
	Path string
	// Version is the normalized (no leading "v", no Config.TagPrefix)
	// version of the release that was installed.
	Version string
	// Tag is that release's exact published tag, which may differ from
	// Version by a TagPrefix and/or a leading "v"
	// (REQ: multi-product-repository).
	Tag string
}

type ManagedBinaryVerifier func(ctx context.Context, detection Detection, binary string, args []string, expectedVersion string) (ExecutableIdentity, error)

type ManagedCommand struct {
	Executable string
	Args       []string
}

type ManagedCommandRunner func(ctx context.Context, executable string, args []string) error

type Manager struct {
	// Name is shown to the user, e.g. "Homebrew".
	Name string
	// UpgradeCommand is the exact command printed for the user to run,
	// e.g. "brew upgrade --cask wb". It is display-only and is never parsed
	// or passed to a shell.
	UpgradeCommand string
	// UpgradeExecutable is the program invoked for an executable managed
	// update. Empty keeps this manager redirect-only for backward
	// compatibility. Configure it through WithExecutableUpgrade so its argv
	// is copied rather than aliased.
	UpgradeExecutable string
	// UpgradeArgs are passed directly to UpgradeExecutable without shell
	// parsing or interpolation.
	UpgradeArgs []string
	// UpgradeSteps are executed in order when non-empty. They allow a manager
	// whose local metadata must be refreshed before upgrade to express both
	// operations as structured argv without invoking a shell. A failed step
	// stops the sequence.
	UpgradeSteps []ManagedCommand
	// PathMarkers are lowercased, '/'-separated substrings; a resolved
	// executable path containing any one of them classifies as this
	// manager's install.
	PathMarkers []string
}

type Options struct {
	// PinnedVersion, when non-empty, installs exactly that release instead
	// of the latest stable one (REQ: version-pin). A leading "v" is
	// optional.
	PinnedVersion string
	// AllowDowngrade permits a PinnedVersion that orders below the running
	// version (REQ: pinned-downgrade-guard). Ignored when PinnedVersion is
	// empty, and ignored when the running version is undetermined (there is
	// no direction to guard).
	AllowDowngrade bool
	// DryRun walks the full decision path and stops before any download or
	// write (REQ: dry-run). See ActionPlanned.
	DryRun bool
	// Confirm, when non-nil, is called with a human-readable description of
	// the version transition (e.g. "1.0.0 → 1.1.0", or "downgrade: 1.1.0 →
	// 1.0.0") before any download begins, and must return whether to
	// proceed. This is the ONLY place Update touches anything resembling
	// user interaction, and it does none of the interaction itself
	// (REQ: no-io-side-effects-in-core) — prompting, or deciding to skip the
	// prompt because a --yes flag was given, or refusing because no
	// terminal is attached (REQ: non-interactive-refusal), all belong to
	// Confirm's implementation. A refusal like the non-interactive one is
	// reported by returning a *Failure (e.g. {Kind: KindNonInteractive})
	// as the error, which Update passes straight through; returning
	// (false, nil) instead means "the user was asked and said no", which
	// Update reports as ActionAborted with a nil error, not a failure.
	// Nil means no confirmation gate at all — Update proceeds immediately.
	Confirm func(transition string) (bool, error)
	// RunManaged is required when the detected Manager opted into executable
	// upgrades. It receives structured argv, never a shell command string.
	RunManaged ManagedCommandRunner
	// VerifyManaged is required alongside RunManaged and probes the CLI found
	// after the manager command using Config.VersionProbeArgs.
	VerifyManaged ManagedBinaryVerifier
	// ReportAvailability is called once after version information is resolved
	// and before confirmation or mutation. Its callback is advisory output only;
	// it cannot alter update control flow.
	ReportAvailability AvailabilityReporter
	// AfterUpdate runs only after an actual successful update, an already-current
	// result, or a successful executable package-manager update. It receives the
	// resolved installed executable identity so integrations can reexec the new
	// binary. An error becomes Outcome.AfterUpdateWarning; it never changes a
	// completed binary update into a failure.
	AfterUpdate AfterUpdateFunc
	// ResolvedTag, when set, names the release tag a caller already resolved
	// via Config.LatestRelease and had confirmed (REQ: update-at-classified-
	// copy). Neither the manual nor the managed path performs its own
	// independent latest-release search when this is set: the target is
	// this tag, not whatever the package would otherwise pick. The one
	// lookup the unpinned path always makes is still performed, but only to
	// confirm this tag is STILL the latest stable release; if a newer one
	// was published in between, the update fails with KindReleaseLookup and
	// changes nothing, so a caller that confirmed one version never installs
	// another. Ignored when PinnedVersion is set — a pin already names an
	// exact target by construction.
	ResolvedTag string
}

type Outcome struct {
	// Action is what happened.
	Action Action
	// Detection is how the running binary's install was classified.
	Detection Detection
	// Result is the version comparison that led to Action, when one was
	// performed.
	Result CheckResult
	// ReleaseCheckWarning records an advisory failure while looking up the
	// latest published release for a managed install. The package manager
	// remains the update authority, so this warning never prevents a redirect
	// or configured manager command from proceeding.
	ReleaseCheckWarning error
	// Target is the normalized version that was (or would be, or was
	// declined to be) installed.
	Target string
	// Downgrade is true when Target orders below the running version, i.e.
	// this was a downgrade (only possible via a pinned Options.
	// PinnedVersion with AllowDowngrade set).
	Downgrade bool
	// PlannedURL is the exact asset URL a non-dry-run call would have
	// fetched for a manual install. Set only when Action is ActionPlanned.
	PlannedURL string
	// PlannedCommand is the exact display command an executable manager
	// would run. Set for a managed ActionPlanned outcome.
	PlannedCommand string
	// PostSwapWarning is set when Action is ActionUpdated and the post-swap
	// version probe did not confirm the expected version, or when
	// ActionManagerExecuted and the installed CLI could not be probed after
	// the manager command completed. The mutation already succeeded — this
	// is a warning to surface, not a failed Update.
	PostSwapWarning error
	// AfterUpdateWarning is set when Options.AfterUpdate could not resolve the
	// installed executable or returned an error. The binary update has already
	// completed, so this is a warning to surface separately, never an Update
	// failure.
	AfterUpdateWarning error
}

type Platform struct {
	GOOS   string
	GOARCH string
}

type Verdict int