cliinstall

type BatchResult struct {
	Host    string
	Results []Result
}

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 InstallEnv struct {
	Env
	// UserHomeDir returns the current user's home directory, used only on
	// non-Windows platforms to build the per-user bin directory.
	UserHomeDir func() (string, error)
	// Getenv reads one environment variable, used for %LOCALAPPDATA% and
	// the destination denylist's Windows roots and $GOROOT.
	Getenv func(string) string
	// MkdirAll creates the per-user bin directory (mode 0755) only when a
	// real, non-dry-run install actually needs it
	// (cli-install#req:per-user-bin-dir: "created only for a real
	// install... when missing").
	MkdirAll func(dir string, perm fs.FileMode) error
	// RunManaged executes `brew install --cask <token>` as structured
	// argv, streaming its own output
	// (cli-install#req:homebrew-cask-install). Required whenever a batch
	// actually runs a (non-print-only) Homebrew install; nil fails that
	// install with KindManagedCommand rather than panicking (see
	// executeHomebrewInstall).
	//
	// This package builds no default implementation itself: doing so would
	// mean deciding what to stream brew's output to, and this core layer
	// MUST NOT touch the terminal or assume any I/O streams
	// (cli-install#req:core-framework-neutral). A caller wires one from its
	// own owned streams — e.g. selfupdate/cliui.ManagedCommandRunner(in,
	// out, errOut) — exactly as selfupdate's own cobracmd adapter wires
	// Options.RunManaged for self-replace.
	RunManaged selfupdate.ManagedCommandRunner
}

type Method int

type Options struct {
	// HostID is the running host's own catalog id
	// (cli-install#req:host-identity-from-catalog). It MUST be a valid
	// catalog id; an absent one is a programming error Install panics on,
	// per that REQ's "caught by the host's tests, not a runtime state
	// users see."
	HostID string
	// Dir is the --dir flag's value; empty when it was not given.
	Dir string
	// Yes skips the confirmation gate (cli-install#req:confirmation-gate),
	// matching selfupdate's own --yes convention.
	Yes bool
	// DryRun walks the full decision path without any write, brew
	// invocation, directory creation, or confirmation
	// (cli-install#req:install-dry-run).
	DryRun bool
	// HomebrewPrintOnly reports a Homebrew install's command instead of
	// running it (cli-install#req:homebrew-cask-install).
	HomebrewPrintOnly bool
	// Env carries every side-effecting dependency.
	Env InstallEnv
	// Confirm asks whether to proceed with every target that would be
	// installed, called at most once per batch, only when at least one
	// target needs it and Yes is false
	// (cli-install#req:confirmation-gate). Its own refusal — no
	// interactive terminal and Yes false — is reported by returning a
	// *selfupdate.Failure{Kind: selfupdate.KindNonInteractive}, exactly as
	// selfupdate.Options.Confirm documents
	// (self-update#req:non-interactive-refusal); Install has no
	// interactive-terminal opinion of its own; it relies entirely on this
	// callback to enforce it.
	Confirm func(names []string) (bool, error)
	// ConfigureRelease optionally overrides a target's resolved
	// selfupdate.Config before it is used to install or resolve that
	// target's release — the release-endpoint injection point
	// cli-install#req:no-network-in-tests requires. Nil keeps the
	// catalog's own defaults (the real GitHub API).
	ConfigureRelease func(target Entry, cfg selfupdate.Config) selfupdate.Config
	// ProbeOptions tunes status probing; the zero value is
	// production-correct (see ProbeOptions).
	ProbeOptions ProbeOptions
}

type Outcome int

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 Result struct {
	// Target is the catalog id this result describes, or — only for
	// OutcomeFailed with a KindUnknownTarget Failure — the raw name that
	// was not a catalog id.
	Target string
	// Outcome classifies what happened to Target.
	Outcome Outcome
	// Method is how Target will be, or was, installed. Meaningful only when
	// Outcome is OutcomeInstalled, OutcomeRedirected, OutcomeDryRun, or
	// OutcomeFailed after a destination was already planned.
	Method Method
	// Destination is the full destination file path for a MethodDirect
	// plan or install; empty for MethodHomebrew.
	Destination string
	// CaskArgv is the exact `brew install --cask <token>` argv for a
	// MethodHomebrew plan, redirect, or install; nil for MethodDirect.
	CaskArgv []string
	// Version and Tag are the release that was (or, for a dry run, would
	// be) installed. Tag is the exact published tag, which may differ from
	// Version by a repository's TagPrefix and/or a leading "v".
	Version string
	Tag     string
	// UpdateHint names the command that updates Target, set only for
	// OutcomeAlreadyInstalled (cli-install#req:already-installed-no-op).
	UpdateHint string
	// Status is Target's probed install state: the pre-install probe for
	// every outcome except OutcomeInstalled, which carries the
	// post-install re-probe (cli-install#req:post-install-verification).
	// Zero when Target was never a valid catalog id.
	Status Status
	// Failure is set exactly when Outcome is OutcomeFailed.
	Failure *selfupdate.Failure
	// Warnings are human-readable, non-fatal notes: a shell command cache
	// hint after a real install, a shadowing notice, a PATH or
	// post-install-verification remedy, or Status's own warnings.
	Warnings []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