cmdutil

type HTTPStatusError struct {
	StatusCode int
	Body       string
}

type ListParams struct {
	// Resource is the canonical resource name used to look up a configured
	// per-resource limit. See clitypes.KnownPaginatedResources.
	Resource string
	// Limit is the value of the command's --limit flag.
	Limit int
	// FallbackDefault applies when neither the flag nor config supplies a limit.
	FallbackDefault int
	// Start is the value of the command's --start flag.
	Start int
	// All requests every item, ignoring pagination entirely.
	All bool
}

type ListSpec[T any] struct {
	// Resource names the collection in error messages and the trailing
	// "Showing x of y <resource>" line.
	Resource string
	// Endpoint is the list path (environment already applied).
	Endpoint string
	// Params configures pagination from the command's flags.
	Params ListParams
	// Query holds extra query parameters, applied after pagination.
	Query url.Values
	// JSON selects raw JSON passthrough output.
	JSON bool

	Headers []string
	Row     func(T) []string
}

type PostActionSpec struct {
	// Path is the fully built action path.
	Path string
	// Body is the optional JSON request body.
	Body any
	// FailureMessage wraps transport and status errors.
	FailureMessage string
	// SuccessMessage is the preformatted human-readable success line.
	SuccessMessage string
	// Timeout optionally extends the client timeout for slow actions.
	Timeout time.Duration
	// JSON prints the decoded response data instead of the success line.
	JSON bool
}

type ResourceRef[D any, S any] struct {
	// Singular and Plural name the resource in prompts and error messages
	// ("container", "containers").
	Singular string
	Plural   string
	// IDHint completes "use <IDHint> or run `<ListCmd>`" guidance
	// ("the container ID", "the volume name").
	IDHint  string
	ListCmd string

	// GetPath builds the GET-by-identifier path; ListPath the list endpoint
	// that Resolve queries with ?search=<identifier>&limit=-1.
	GetPath  func(envID, identifier string) string
	ListPath func(envID string) string
	// SearchCandidates replaces the standard list search for resources with
	// specialized matching rules.
	SearchCandidates func(context.Context, *client.Client, string) ([]S, error)
	// SelectCandidate replaces the standard ambiguity handling while keeping
	// direct lookup and not-found behavior in Resolve.
	SelectCandidate func([]S, string, bool) (*S, error)
	// Validate checks a successful direct lookup before Resolve returns it.
	Validate func(D, string) error

	// Matches reports whether a listed item matches the identifier.
	Matches func(item S, identifierLower, original string) bool
	// Label renders one match as an interactive prompt option.
	Label func(S) string
	// Promote converts a selected summary into the detail shape.
	Promote func(S) *D

	// IDOf enables the last-resort ID-prefix scan over the full list for
	// resources addressed by opaque IDs (containers, images). Leave nil to
	// skip that fallback.
	IDOf func(S) string

	// Exact optionally reports an exact identifier match. When set and
	// exactly one search match is exact, it wins without prompting even if
	// broader substring matches exist.
	Exact func(item S, identifierLower, original string) bool
}