cliinstall

type BatchFailure struct {
	Failures []*selfupdate.Failure
}

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

	// SelfUpdateHooks reports whether this CLI's own `self-update` performs
	// after-update work beyond the swap itself — a daemon restart, a skills
	// re-sync — via selfupdate.Options.AfterUpdate
	// (cli-install#req:self-update-hook-hint). Upgrade does not run another
	// CLI's hooks itself; when a target other than the host has this set and
	// is upgraded or has its manager command executed, the result carries a
	// `<target> self-update` finish hint instead. True today for wb (daemon
	// restart, skills sync) and codegrapher (skills sync) — verified against
	// each repository's own self-update command wiring; every other catalog
	// entry leaves this at its false zero value.
	SelfUpdateHooks bool
}

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 by Execute, only when at
	// least one target needs it and Yes is false
	// (cli-install#req:confirmation-gate). It receives the already-planned
	// []Result for exactly those pending targets — version, tag, asset URL,
	// destination or cask argv all already resolved by Plan — so a caller
	// renders the confirmation prompt (and, in a Cobra host, the
	// details-before-install preview) from the SAME data Execute is about
	// to act on, never a second, independently-resolved lookup. 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); Execute has no
	// interactive-terminal opinion of its own; it relies entirely on this
	// callback to enforce it.
	Confirm func(planned []Result) (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 or a
	// still-planned pending target, would be) installed. Tag is the exact
	// published tag, which may differ from Version by a repository's
	// TagPrefix and/or a leading "v". Both are resolved exactly once, by
	// Plan, and Execute installs precisely this Tag — never re-resolving
	// "latest" a second time (cli-install#req:direct-release-install).
	Version string
	Tag     string
	// AssetURL is the exact release-asset URL a MethodDirect plan will
	// download; empty for MethodHomebrew
	// (cli-install#req:details-before-install: "the exact... asset URL").
	AssetURL 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
	// contains filtered or unexported fields
}

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
	// ResolvedPath is Path with its symlinks followed (cli-install#req:
	// upgrade-per-target-policy: "The path passed for replacement MUST be
	// the symlink-resolved path"), or exactly Path when Env.EvalSymlinks is
	// nil, resolution fails, or Path is not itself a symlink. Empty when
	// State is NotInstalled. Task-21's own upgrade planning is the reason
	// this is carried on Status rather than re-resolved later: a symlink
	// target can change between probing and upgrading, and re-resolving at
	// upgrade time would silently reopen the same TOCTOU window
	// cli-install#req:install-never-overwrites' no-replace placement exists
	// to close on the install side.
	ResolvedPath 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 UpgradeBatchResult struct {
	Host    string
	Results []UpgradeResult
}

type UpgradeOptions struct {
	// HostID is the running host's own catalog id
	// (cli-install#req:host-identity-from-catalog). Must be a valid catalog
	// id; PlanUpgrade panics otherwise, matching Plan's own contract.
	HostID string
	// All selects every catalog id whose status is installed, plus the
	// host, regardless of the relevance matrix (cli-install#req:upgrade-
	// targets). Names given alongside All is a caller/usage-layer concern
	// (cobracmd's own "--all takes no target names" refusal, mirroring
	// install's own usage check) — PlanUpgrade itself treats All as taking
	// priority and simply ignores any names passed alongside it. An empty
	// names list with All false is ALSO treated as the All set
	// (cli-install#req:upgrade-no-args-reports: the bare, no-argument
	// report runs the read-only check over the --all set), so a caller
	// need not special-case the truly-bare invocation.
	All bool
	// Yes skips the confirmation gate, matching Options.Yes.
	Yes bool
	// DryRun walks the full decision path without confirming, replacing,
	// or running any manager command (cli-install#req:upgrade-batch-
	// semantics inheriting cli-install#req:install-dry-run). Upgrade
	// returns PlanUpgrade's own result unchanged when set, exactly as
	// Install does for Options.DryRun.
	DryRun bool
	// Env carries every side-effecting dependency: status probing (via the
	// embedded Env) and the managed command runner (RunManaged) upgrade
	// shares with install. Getenv additionally supplies GH_TOKEN/
	// GITHUB_TOKEN for the bearer-auth HTTPClient default (cli-install#req:
	// upgrade-release-lookups-bounded).
	Env InstallEnv
	// Confirm asks whether to proceed with every target that would be
	// upgraded, called at most once per batch by ExecuteUpgrade, exactly
	// as Options.Confirm — it receives the already-planned pending
	// []UpgradeResult (current, latest, verdict, method, command all
	// already resolved).
	Confirm func(pending []UpgradeResult) (bool, error)
	// ConfigureRelease optionally overrides a non-host target's resolved
	// selfupdate.Config before it is used to look up or install 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, bearer-authenticated
	// per HostConfig's own doc comment).
	ConfigureRelease func(target Entry, cfg selfupdate.Config) selfupdate.Config
	// ProbeOptions tunes status-probe concurrency and per-target time
	// budget; the zero value is production-correct.
	ProbeOptions ProbeOptions

	// HostConfig is the host's OWN self-update selfupdate.Config — built
	// the identical way its `self-update` command builds one, including
	// any manager overrides or extra Managers it adds beyond its catalog
	// entry (cli-install#req:host-target-is-running-binary: "The host MUST
	// use its own self-update Config and options... so upgrade <self> and
	// self-update reach the same library call"). Required whenever the
	// host is a candidate target (named explicitly, or under All/the bare
	// report). When its HTTPClient is left nil, PlanUpgrade/ExecuteUpgrade
	// default it to a bearer-authenticated client exactly as it does for
	// every other target — see the package-level githubHTTPClient doc
	// comment.
	HostConfig selfupdate.Config
	// HostAfterUpdate is the host's own after-update hook, passed straight
	// through to selfupdate.Options.AfterUpdate only for the host's own
	// REAL (non-dry-run) UpdateAt call, in ExecuteUpgrade — the SAME
	// closure its `self-update` command configures, so `upgrade <self>`
	// runs the identical hook `self-update` does
	// (cli-install#req:self-update-equals-upgrade-self), including when
	// the host is already current (task-22 review B2: ExecuteUpgrade makes
	// a second real UpdateAt call for an already-current host specifically
	// because selfupdate.Config.UpdateAt's own runAfterUpdate skips the
	// hook under DryRun, so PlanUpgrade's own DryRun(true) call alone never
	// fires it — see ExecuteUpgrade's own doc comment). Never used for any
	// other target: v1 reports a FinishHint instead of running another
	// CLI's hooks (cli-install#req:self-update-hook-hint).
	HostAfterUpdate selfupdate.AfterUpdateFunc
	// DetectHost resolves the host's own install classification. Nil
	// defaults to opts.HostConfig.DetectSelf — the real running executable
	// — exactly matching what the host's own `self-update` command would
	// call (cli-install#req:host-target-is-running-binary; task-22 review
	// S1: classification MUST come from DetectSelf, not a rebuilt
	// `<hostDir>/<hostID>` path, which can name the wrong file for a
	// renamed or aliased binary). Tests inject a fake to avoid depending on
	// the actual test binary's own location; production callers leave this
	// nil.
	DetectHost func() (selfupdate.Detection, error)
	// VerifyManaged probes an executable managed target after its manager
	// command completes, passed straight through to
	// selfupdate.Options.VerifyManaged for every target including the host
	// (task-22 review S2: this MUST be the same verifier `self-update`
	// itself uses — filtering PATH candidates by the detected manager's own
	// markers — never an ad hoc probe with no manager filter). cliinstall
	// itself has no opinion on how verification works; a Cobra host
	// defaults this to selfcliui.VerifyManagedBinary, exactly as its own
	// self-update command does. Required whenever any candidate target
	// might be an executable managed install; nil makes such an upgrade
	// fail with selfupdate.KindManagedCommand, matching UpdateAt's own
	// "not configured" failure.
	VerifyManaged selfupdate.ManagedBinaryVerifier

	// LookupConcurrency bounds how many targets' latest-release lookups run
	// at once. Zero defaults to 4 (cli-install#req:upgrade-release-
	// lookups-bounded).
	LookupConcurrency int
	// LookupTimeout bounds each individual latest-release lookup. Zero
	// defaults to 15 seconds (cli-install#req:upgrade-release-lookups-
	// bounded).
	LookupTimeout time.Duration
}

type UpgradeOutcome int

type UpgradeResult struct {
	// Target is the catalog id this result describes.
	Target string
	// Host is true exactly for the row describing the running host itself
	// (cli-install#req:host-target-is-running-binary).
	Host bool
	// Outcome classifies what happened to Target — REQ: upgrade-batch-
	// semantics' "action".
	Outcome UpgradeOutcome

	// InstallMethod classifies Target's install (cli-install#req:upgrade-
	// per-target-policy): for a non-host target this follows DetectSelf's
	// own rule (managed on either the PATH-found or symlink-resolved path,
	// otherwise manual or ambiguous judged on the resolved path alone); for
	// the host it is literally selfupdate.Config.DetectSelf's own
	// classification of the running executable (REQ: host-target-is-
	// running-binary — task-22 review S1), not a rebuilt path. Meaningful
	// only when Target was located and Installed.
	InstallMethod selfupdate.InstallMethod
	// Manager identifies the owning package manager when InstallMethod is
	// selfupdate.Managed; nil otherwise.
	Manager *selfupdate.Manager
	// ResolvedPath is the file this upgrade acts on: the symlink-resolved
	// path for a Manual or Ambiguous classification (REQ: upgrade-per-
	// target-policy: "The path passed for replacement MUST be the
	// symlink-resolved path, so a symlink is kept"), or the located path
	// for a Managed one, whose file is never written directly.
	ResolvedPath string

	// Current is Target's installed version: the probed Status.Version for
	// a non-host target, or the host's own Config.CurrentVersion for the
	// host row — never the version a status probe of the host's own PATH
	// copy would have found (REQ: host-target-is-running-binary).
	Current string
	// Latest is the resolved latest stable release's normalized version,
	// set once a lookup has completed.
	Latest string
	// Tag is Latest's exact published tag, passed to
	// selfupdate.Options.ResolvedTag so Execute never independently
	// re-searches for "latest" a second time (cli-install#req:upgrade-
	// resolves-release-once) — UpdateAt's own re-verification that this
	// tag is STILL latest is a separate, deliberate check documented on
	// that call, not a second search.
	Tag string
	// Verdict is the comparison between Current and Latest, set once a
	// lookup has completed. Zero (selfupdate.UpToDate) when no lookup ran.
	Verdict selfupdate.Verdict

	// Command is the manager's display upgrade command, set whenever
	// Manager is non-nil, regardless of Outcome. Empty for a manager that
	// carries only Hint instead — e.g. the built-in system-package manager,
	// which has no single copy-pasteable command (see selfupdate.Manager.
	// UpgradeHint). A renderer MUST NOT print an empty Command after a
	// "Run:"-style prefix.
	Command string
	// Hint is the manager's UpgradeHint — human-readable prose naming how
	// to update when there is no single Command to print — set whenever
	// Manager is non-nil, regardless of Outcome. At most one of Command and
	// Hint is normally non-empty; a renderer shows Hint in a natural
	// sentence, never after a "Run:" prefix the way Command is.
	Hint string
	// AssetURL is the exact release-asset URL a pending manual upgrade
	// would fetch, taken from selfupdate.Outcome.PlannedURL
	// (cli-install#req:upgrade-batch-semantics: "version transition, asset
	// URL and path" — task-22 review S3). Empty for a managed target (its
	// Command already names the action) and for any terminal outcome that
	// never reached a planned replacement.
	AssetURL string
	// NonReleaseBuild is true when Current was classified a non-release
	// build (cli-install#req:upgrade-skips-non-release-builds) and this
	// target was offered anyway because it was named explicitly — the
	// confirmation prompt tags such a target by name (task-22 review S3).
	NonReleaseBuild bool
	// InstallHint names the remedy for UpgradeOutcomeNotInstalled:
	// "<host> install <target>".
	InstallHint string
	// FinishHint names the remedy for a non-host target whose catalog entry
	// declares SelfUpdateHooks and was Upgraded or had its manager command
	// executed: "<target> self-update" (cli-install#req:self-update-hook-
	// hint). Empty otherwise; upgrade never runs another CLI's hooks
	// itself.
	FinishHint string

	// Status is Target's probed install state, as REQ: status-probe-order
	// found it before this upgrade acted (or, for a target this upgrade
	// never touches, its only state). Always zero for the host: the host's
	// classification and version come from DetectSelf/Config, never from a
	// status probe of its own PATH copy (task-22 review M2) — a separate
	// PATH copy, if one exists, is named only in Warnings and OtherPaths.
	Status Status
	// OtherPaths lists additional located copies of Target, exactly as
	// Status.OtherPaths does for a non-host row; for the host row this is
	// the probed PATH copy (if any) instead, since Status itself is zero.
	OtherPaths []string
	// Failure is set exactly when Outcome is UpgradeOutcomeFailed or
	// UpgradeOutcomeRefused.
	Failure *selfupdate.Failure
	// Warnings are human-readable, non-fatal notes: a non-release-build
	// notice, an ambiguous-install guidance message, another-PATH-copy
	// warning for the host, a post-swap or after-update warning, a finish
	// hint's own prose, or Status's own warnings.
	Warnings []string
}

type VersionSource int