cliinstall

type Entry struct {
	// ID is the catalog id, equal to the binary name
	// (cli-install#req:host-identity-from-catalog).
	ID string
	// Homepage is the CLI's canonical homepage URL.
	Homepage string
	// Description is a one-line description shown in a listing row.
	Description string
	// Details is a longer description of at most a few short paragraphs,
	// shown before a confirmation prompt
	// (cli-install#req:details-before-install).
	Details string

	// Repository is "owner/repo" on GitHub that publishes this CLI's
	// releases — see selfupdate.Config.Repository.
	Repository string
	// TagPrefix selects this binary's releases within Repository when that
	// repository publishes more than one product's releases — see
	// selfupdate.Config.TagPrefix.
	TagPrefix string
	// Managers are the package managers that might own this binary's
	// install, exactly as this CLI's own self-update declares them — see
	// selfupdate.Config.Managers.
	Managers []selfupdate.Manager
	// SupportedPlatforms restricts install and self-replace to the
	// GOOS/GOARCH pairs this CLI's release actually publishes — see
	// selfupdate.Config.SupportedPlatforms.
	SupportedPlatforms []selfupdate.Platform
	// VersionProbeArgs are the arguments run against a newly installed copy
	// to confirm its version. A zero value leaves selfupdate.Config's own
	// default ({"--version"}) in effect.
	VersionProbeArgs []string
	// UndeterminedVersions lists the CurrentVersion values that mean "this
	// build cannot say its own version". A zero value leaves
	// selfupdate.Config's own default ({"dev"}) in effect.
	UndeterminedVersions []string
	// AssetName names this CLI's release archive for one version/platform
	// combination. Nil leaves selfupdate.Config's GoReleaser-shaped default
	// in effect, which every catalog entry's archive naming matches.
	AssetName func(binary, version, goos, goarch string) string
	// ChecksumsName names this CLI's release checksums file for one
	// version. Nil leaves selfupdate.Config's GoReleaser-shaped default
	// ("<binary>_<version>_checksums.txt") in effect; some CLIs publish a
	// single flat "checksums.txt" instead and override this.
	ChecksumsName func(binary, version string) string

	// CaskToken is the argument to `brew install --cask`, tap-qualified
	// (e.g. "sneat-dev/tap/wb"). Empty means this CLI publishes no
	// Homebrew cask.
	CaskToken string
	// CaskOS lists the GOOS values ("darwin", "linux") CaskToken's cask
	// supports. Empty when CaskToken is empty.
	CaskOS []string

	// LegacyVersionSignatures optionally lists bare `--version` output
	// patterns that identify an old build of this CLI, for the
	// status-probe-order fallback step
	// (cli-install#req:status-probe-order). Empty when no such pattern is
	// declared for this CLI.
	LegacyVersionSignatures []string
}

type Env struct {
	// PathDirs returns the current PATH's directories, in order. It need
	// not exclude relative entries itself — Probe filters those
	// defensively — but DefaultEnv's implementation does anyway, since a
	// relative entry is never meaningful to report as a directory that
	// was searched.
	PathDirs func() []string
	// HostDir returns the running host CLI's own executable directory
	// (cli-install#req:status-locate). Returning a non-nil error is
	// treated as "no host directory to search", not a fatal Probe error.
	HostDir func() (string, error)
	// IsExecutable reports whether path names an executable regular file
	// — "not merely a file of that name" (cli-install#req:status-locate).
	IsExecutable func(path string) bool
	// EvalSymlinks resolves path's symlinks for classification
	// (cli-install#req:status-locate). May be left nil, in which case
	// classification uses only the unresolved path.
	EvalSymlinks func(path string) (string, error)
	// Run executes path with args directly, without a shell, with empty
	// stdin, "NO_COLOR=1" set, and returns the combined stdout+stderr —
	// so a probed binary's error or usage text is still available for
	// Status.Output when a step doesn't recognize the subcommand. Run
	// MUST honor ctx's deadline by killing the process when it expires
	// (cli-install#req:status-probe-bounded) and MUST NOT itself retry,
	// write any file, or make a network request.
	Run func(ctx context.Context, path string, args []string) ([]byte, error)
}

type ProbeOptions struct {
	// Concurrency is how many targets are located and probed at once.
	// Zero defaults to 4.
	Concurrency int
	// Budget is the per-target time budget covering every probe step.
	// Zero defaults to 3 seconds.
	Budget time.Duration
}

type Relevance struct {
	// Target is the relevant CLI's catalog id.
	Target string
	// Text is the relevance text written for this exact host/target pair.
	Text string
}

type State int

type Status struct {
	// ID is the catalog id this Status describes.
	ID string
	// State is this target's install state.
	State State

	// Path is the primary reported copy: the first PATH match, or — when
	// no copy is on PATH — the first copy found in the host directory or
	// dir (cli-install#req:status-locate). Empty when State is
	// NotInstalled.
	Path string
	// OnPath reports whether Path itself was found on an absolute PATH
	// entry. False means Path was found only in the host directory or
	// dir, in which case Warnings carries a not-on-PATH warning.
	OnPath bool
	// OtherPaths lists every other located copy of this target, in the
	// order they were found (cli-install#req:status-locate: "additional
	// copies... count in text, full paths in JSON").
	OtherPaths []string

	// Method classifies Path's install method, checking both Path itself
	// and its symlink-resolved form against every manager declared
	// anywhere in the compiled catalog, preferring managed
	// (cli-install#req:status-locate). Meaningful only when State is
	// Installed or Unrecognized.
	Method selfupdate.InstallMethod
	// Manager identifies the owning package manager when Method is
	// selfupdate.Managed; nil otherwise.
	Manager *selfupdate.Manager

	// Version, Commit, Date and DateSource are read from whichever step
	// VersionSource names. Commit and Date are "" when unknown; a raw
	// "none" or "unknown" token from a text probe is normalized to ""
	// (cli-install#req:status-probe-order). Meaningful only when State is
	// Installed.
	Version    string
	Commit     string
	Date       string
	DateSource string
	// VersionSource names the step that produced Version/Commit/Date/
	// DateSource.
	VersionSource VersionSource

	// Output is the trimmed combined output of the last probe step that
	// produced any, kept for display when State is Unrecognized
	// (cli-install#req:status-probe-order: "reported with its path and
	// the output that was seen").
	Output string

	// Warnings are human-readable, non-fatal notes: a not-on-PATH warning
	// when OnPath is false, or a timeout warning when this target's probe
	// budget was exhausted.
	Warnings []string
}

type VersionSource int