cobracmd

type CommandOptions struct {
	// Use is the command name, including any argument hint shown in help
	// text. Defaults to "install [name...]".
	Use string
	// Short is the one-line help text. Defaults to a generic description.
	Short string
	// Aliases are additional names the command responds to.
	Aliases []string
	// HostID is the running host's own catalog id
	// (cli-install#req:host-identity-from-catalog). New panics if it is not
	// a valid catalog id — a programming error the host's own tests must
	// catch, never a runtime state a user sees, per that REQ.
	HostID string
	// Errors maps outcomes to the host's own error type. Required for a
	// host that wants distinguishable exit codes; a nil Errors makes every
	// failure return the underlying error unchanged.
	Errors ErrorMapper
	// Interactive reports whether the process is attached to an interactive
	// terminal, used to implement REQ: non-interactive-refusal for the
	// batch confirmation prompt. Passed straight through to
	// cliui.ConfirmOptions.Interactive; nil means that package's own
	// default. Tests should always override this.
	Interactive func() bool
	// HomebrewPrintOnly reports a Homebrew install's command instead of
	// running it, passed straight through to cliinstall.Options
	// (cli-install#req:homebrew-cask-install).
	HomebrewPrintOnly bool
	// ConfigureRelease optionally overrides a target's resolved
	// selfupdate.Config before it is used to resolve 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).
	ConfigureRelease func(target cliinstall.Entry, cfg selfupdate.Config) selfupdate.Config
	// Env carries every side-effecting dependency Probe and Install use.
	// Left unset (a zero cliinstall.InstallEnv), New uses
	// cliinstall.DefaultInstallEnv() — the real host. Tests always set
	// this, exactly as cli-install#req:no-network-in-tests requires.
	Env cliinstall.InstallEnv
	// ProbeOptions tunes status-probe concurrency and per-target time
	// budget; the zero value is production-correct (see
	// cliinstall.ProbeOptions).
	ProbeOptions cliinstall.ProbeOptions
}

type ErrorMapper interface {
	// Failure maps a non-nil command error into the host's own error type:
	// a *UsageError, Plan's own batch-level *selfupdate.Failure (an unknown
	// name), Execute's own batch-level *selfupdate.Failure (no interactive
	// terminal and --yes not given), or a *cliinstall.BatchFailure carrying
	// every failed target's own typed *selfupdate.Failure
	// (cli-install#req:host-owned-exit-codes: "A batch failure MUST expose
	// each target's typed failure" — task-5 review S3). See
	// cliinstall.BatchFailure's own doc comment for the suggested
	// precedence a host applies when it wants one exit code for a batch
	// that failed for more than one reason.
	Failure(err error) error
}

type UpgradeCommandOptions struct {
	// Use is the command name, including any argument hint shown in help
	// text. Defaults to "upgrade [name...]".
	Use string
	// Short is the one-line help text. Defaults to a generic description.
	Short string
	// Aliases are additional names the command responds to. REQ: update-
	// alias-policy: never pass "update" here.
	Aliases []string
	// HostID is the running host's own catalog id
	// (cli-install#req:host-identity-from-catalog). NewUpgrade panics if it
	// is not a valid catalog id, matching install's own New.
	HostID string
	// Errors maps outcomes to the host's own error type. Implement
	// UpgradeErrorMapper (not just ErrorMapper) to receive the upgrades-
	// available signal cli-install#req:upgrade-check requires; a plain
	// ErrorMapper, or a nil Errors, simply never gets that call.
	Errors ErrorMapper
	// Interactive reports whether the process is attached to an interactive
	// terminal, used to implement REQ: non-interactive-refusal for the
	// batch confirmation prompt. Passed straight through to
	// cliui.ConfirmOptions.Interactive; nil means that package's own
	// default. Tests should always override this.
	Interactive func() bool
	// ConfigureRelease optionally overrides a non-host target's resolved
	// selfupdate.Config before it is used to look up or apply that target's
	// upgrade — the release-endpoint injection point cli-install#req:no-
	// network-in-tests requires. Nil keeps the catalog's own defaults.
	ConfigureRelease func(target cliinstall.Entry, cfg selfupdate.Config) selfupdate.Config
	// Env carries every side-effecting dependency status probing and
	// upgrading use. Left unset (a zero cliinstall.InstallEnv), NewUpgrade
	// uses cliinstall.DefaultInstallEnv() — the real host. Tests always set
	// this.
	Env cliinstall.InstallEnv
	// ProbeOptions tunes status-probe concurrency and per-target time
	// budget; the zero value is production-correct.
	ProbeOptions cliinstall.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). Required whenever the
	// host is a candidate target: named explicitly, included under --all, or
	// part of the bare report's own --all set (i.e. essentially always — a
	// host that never wants itself offered has no way to opt out short of
	// naming every OTHER target explicitly and never using --all or the bare
	// report).
	HostConfig selfupdate.Config
	// HostAfterUpdate is the host's own after-update hook — 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).
	HostAfterUpdate selfupdate.AfterUpdateFunc
	// DetectHost overrides how the host's own install is classified,
	// passed straight through to cliinstall.UpgradeOptions.DetectHost. Nil
	// (the production default) uses opts.HostConfig.DetectSelf, exactly
	// what the host's own `self-update` command calls (cli-install#req:
	// host-target-is-running-binary; task-22 review S1). Tests inject a
	// fake here so they never depend on the real running test binary's own
	// path.
	DetectHost func() (selfupdate.Detection, error)
	// VerifyManaged probes an executable managed target after its manager
	// command completes, passed straight through to cliinstall.
	// UpgradeOptions.VerifyManaged. Nil defaults to
	// selfcliui.VerifyManagedBinary — the SAME verifier the host's own
	// `self-update` command uses, which filters PATH candidates by the
	// detected manager's own markers (task-22 review S2: a bespoke,
	// manager-blind probe could hand AfterUpdate the wrong executable's
	// identity).
	VerifyManaged selfupdate.ManagedBinaryVerifier

	// LookupConcurrency and LookupTimeout tune PlanUpgrade's own release-
	// lookup bounds (cli-install#req:upgrade-release-lookups-bounded); zero
	// keeps cliinstall.UpgradeOptions' own defaults (4, 15s).
	LookupConcurrency int
	LookupTimeout     time.Duration
}

type UpgradeErrorMapper interface {
	ErrorMapper
	// UpgradesAvailable is called with every target whose Verdict is
	// selfupdate.UpdateAvailable or selfupdate.Undetermined, mirroring
	// self-update's own UpdateAvailable mapping (cli-install#req:upgrade-
	// check: "Targets that are ahead of latest or skipped as non-release
	// builds MUST NOT count"). Never called for the bare, no-argument
	// report (cli-install#req:upgrade-no-args-reports: "MUST exit
	// successfully... whether or not upgrades are available") — only for an
	// explicit `--check` over named targets or `--all`.
	UpgradesAvailable(results []cliinstall.UpgradeResult) error
}

type UsageError struct{ Err error }